home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 51 / Amiga Format CD51 (2000-03-10)(Future Publishing)(GB)[!][issue 2000-04].iso / -in_the_mag- / workbench / term_4.8 / extras / source / gtlayout-source.lha / gtlayout.doc < prev    next >
Text File  |  1997-09-22  |  131KB  |  3,873 lines
  1. TABLE OF CONTENTS
  2.  
  3. gtlayout.library/--background--
  4. gtlayout.library/--version--
  5. gtlayout.library/LT_Activate
  6. gtlayout.library/LT_BeginRefresh
  7. gtlayout.library/LT_BuildA
  8. gtlayout.library/LT_CatchUpRefresh
  9. gtlayout.library/LT_CreateHandleTagList
  10. gtlayout.library/LT_DeleteHandle
  11. gtlayout.library/LT_DeleteWindowLock
  12. gtlayout.library/LT_DisposeMenu
  13. gtlayout.library/LT_EndGroup
  14. gtlayout.library/LT_EndRefresh
  15. gtlayout.library/LT_Exit
  16. gtlayout.library/LT_FindMenuCommand
  17. gtlayout.library/LT_GetAttributesA
  18. gtlayout.library/LT_GetCode
  19. gtlayout.library/LT_GetIMsg
  20. gtlayout.library/LT_GetMenuItem
  21. gtlayout.library/LT_GetWindowUserData
  22. gtlayout.library/LT_HandleInput
  23. gtlayout.library/LT_Init
  24. gtlayout.library/LT_LabelChars
  25. gtlayout.library/LT_LabelWidth
  26. gtlayout.library/LT_LayoutMenusA
  27. gtlayout.library/LT_LevelWidth
  28. gtlayout.library/LT_LockWindow
  29. gtlayout.library/LT_MenuControlTagList
  30. gtlayout.library/LT_NewA
  31. gtlayout.library/LT_NewLevelWidth
  32. gtlayout.library/LT_NewMenuTagList
  33. gtlayout.library/LT_NewMenuTemplate
  34. gtlayout.library/LT_PressButton
  35. gtlayout.library/LT_RebuildTagList
  36. gtlayout.library/LT_Refresh
  37. gtlayout.library/LT_ReplyIMsg
  38. gtlayout.library/LT_SetAttributesA
  39. gtlayout.library/LT_ShowWindow
  40. gtlayout.library/LT_UnlockWindow
  41. gtlayout.library/LT_UpdateStrings
  42. gtlayout.library/--background--               gtlayout.library/--background--
  43.  
  44.    NOTES
  45.     1. General information
  46.  
  47.     1.1 Purpose
  48.  
  49.     The GUI code included in this archive helps to create user interfaces
  50.     using gadtools.library with a minimum of effort. The code
  51.     automatically takes care of the font to be used, making the user
  52.     interface font independent. Localizing support is built right into
  53.     the code, just install a callback hook and pass numeric IDs for the
  54.     gadget labels: the code will invoke your hook in order to get the
  55.     text required. Keystroke activation of gadgets is also taken care
  56.     of, in fact the code will -- unless told not to do so -- assign keyboard
  57.     shortcuts to the gadgets created all on its own. Every effort has been
  58.     made to make the code reentrant, so it can be put into a shared library.
  59.     If a user interface does not fit onto a screen provisions are made to
  60.     choose a smaller font and to rescale the window contents until they fit.
  61.     Last but not least the user interface code offers transparent extensions
  62.     to the standard gadtools.library objects, such as LISTVIEW_KIND objects
  63.     which respond to double-clicks or STRING_KIND objects which can be used
  64.     to enter password text as they will not display the characters entered.
  65.  
  66.  
  67.     1.2 Distribution
  68.  
  69.     The code is *free*, you don't need to pay any money to use it, nor
  70.     do you need to quote my name in the documentation, the program or
  71.     anywhere else. You are allowed to make changes to the code, but if
  72.     you stumble across any bugs or even know how to fix them, please
  73.     let me know. It does not matter whether you intend to sell a program
  74.     to use the code, use the code in shareware, gift-ware, freeware or
  75.     etc.-ware programs: the code still remains royalty-free.
  76.  
  77.  
  78.     1.3 Caveats
  79.  
  80.     The code is pretty large, about 80K-100K bytes in size. Not all
  81.     gadtools.library type objects are supported, notably
  82.     GENERIC_KIND objects. The code is not as flexible as
  83.     gadtools.library, so certain things which are easily done using
  84.     gadtools.library may be pretty difficult or even impossible.
  85.     The code is written entirely in `C' and requires SAS/C to
  86.     compile. Some parts of the code are highly recursive; I haven't
  87.     tested how much stack they might require in certain cases,
  88.     but I recommend that you don't overuse the grouping feature.
  89.     The data structures required to create and maintain the
  90.     user interface are huge, a single window might require more
  91.     than 4K-6K of memory. Proportional font support only works
  92.     well starting with Kickstart v39 and up, v2.04 will probably
  93.     not look quite that pretty.
  94.  
  95.  
  96.     2. Programming
  97.  
  98.     2.1 Client libraries required for link library version
  99.  
  100.     You need to have SysBase and GadToolsBase initialized in order to make
  101.     use of the code, i.e. your code has to do
  102.     WaitPort()...GT_GetIMsg()...GT_ReplyIMsg all on its own. The code makes
  103.     use of the memory pools introduced in exec.library v39, but calls the
  104.     equivalent routines in amiga.lib. Note: as of this writing the pools
  105.     code in amiga.lib v40.14 is broken, so you need to link with Mike
  106.     Sinz' fixed pools.lib.
  107.  
  108.  
  109.     2.2 Invocation procedure
  110.  
  111.     The typical invocation procedure looks roughly like this:
  112.  
  113.        LT_Init();    // only for link library version
  114.        :
  115.        :
  116.           LT_CreateHandleTags();
  117.              LT_New();
  118.              :
  119.              :
  120.              LT_New();
  121.                 LT_Build();
  122.                    LT_HandleInput();
  123.           LT_DeleteHandle();
  124.        :
  125.        :
  126.        LT_Exit();    // only for link library version
  127.  
  128.     You need to call LT_Init() only once in your program, it will initialize
  129.     the libraries and global data structures required by the user interface
  130.     code. When you are finished with the user interface and your program is
  131.     about to exit you need to call LT_Exit() or memory will get lost.
  132.     Note that LT_Init() is not protected against multiple invocations. If
  133.     called repeatedly memory will get lost which can never be reclaimed.
  134.     However, LT_Exit() is protected against multiple invocations, you can
  135.     also call it before ever giving LT_Init() a call, but I doubt this
  136.     would make much sense. If you are using the shared gtlayout.library
  137.     no call to LT_Init()/LT_Exit() is necessary as these calls are already
  138.     wrapped into the library opening code.
  139.        Before you can actually start building a window layout a call to
  140.     LT_CreateHandleTags() needs to be made. You need to pass in a pointer
  141.     to the Screen your user interface window is to be opened on and,
  142.     optionally, a few tags to control the look and performance of the
  143.     interface. *Never* close the screen in question before calling
  144.     LT_DeleteHandle() or nasty things will happen. For public screens
  145.     the code will try to lock the screen in question. With the handle
  146.     LT_CreateHandleTags() returned you can call LT_New() to build the
  147.     user interface. When finished a call to LT_Build() will finally
  148.     open a window and place the gadgets inside. A pointer to the
  149.     Window created will be returned, ready to be used for the
  150.     WaitPort()...GT_GetIMsg()...LT_HandleInput()...GT_ReplyIMsg()
  151.     loop. When finished, a call to LT_DeleteHandle() will close the
  152.     window and release all the memory associated with it. The design
  153.     of the interface code is similar to the corresponding calls in
  154.     gadtools.library, i.e. you don't need to worry about LT_New()
  155.     failing to allocate memory for the objects required. When it comes
  156.     to LT_Build() the code will know about any trouble which would
  157.     show up during previous invocations of LT_New(). In essence,
  158.     if LT_Build() returns NULL something is wrong.
  159.  
  160.  
  161.     2.3 Hierarchic grouping
  162.  
  163.     The basic building block of the user interface is a group, either
  164.     a horizontal or a vertical group. Adding gadgets or other objects
  165.     to a horizontal group will place them side by side from left to
  166.     right. A vertical group causes objects to be place from top to
  167.     bottom in one straight line. Groups help to arrange objects
  168.     neatly stacked, centered and properly aligned with other
  169.     members of the group.
  170.  
  171.     MUCHO IMPORTANTE: there is a bug lurking in the code which I never
  172.     had the luck to find and fix. One would expect to create
  173.     user interface structures like this:
  174.  
  175.        <group start>
  176.           <button>
  177.           <list>
  178.           <group start>
  179.              <slider>
  180.              <text>
  181.           <group end>
  182.           <button>
  183.        <group end>
  184.  
  185.     However, it is in fact not possible to mix gadgets and groups.
  186.     Thus, the user interface structure would have to look like this:
  187.  
  188.        <group start>
  189.           <group start>
  190.              <button>
  191.              <list>
  192.           <group end>
  193.           <group start>
  194.              <slider>
  195.              <text>
  196.           <group end>
  197.           <group start>
  198.              <button>
  199.           <group end>
  200.        <group end>
  201.  
  202.     Or in other words: groups only mix with other groups.
  203.  
  204.     You build groups using three different object types. In this
  205.     context `object type' refers to a specific numeric value the
  206.     LT_New() routine knows which will cause it to add another leaf
  207.     to the user interface structure tree. Here is an example:
  208.  
  209.        struct LayoutHandle *Handle;
  210.  
  211.        if(Handle = LT_CreateHandleTags(NULL,
  212.           LAHN_AutoActivate,FALSE,
  213.        TAG_DONE))
  214.        {
  215.           struct Window *Window;
  216.  
  217.           LT_New(Handle,
  218.              LA_Type,      VERTICAL_KIND,  /* A vertical group. */
  219.              LA_LabelText, "Main group",   /* Group title text. */
  220.           TAG_DONE);
  221.           {
  222.              LT_New(Handle,
  223.                 LA_Type,      BUTTON_KIND, /* A plain button. */
  224.                 LA_LabelText, "A button",
  225.                 LA_ID,        11,
  226.              TAG_DONE);
  227.  
  228.              LT_New(Handle,
  229.                 LA_Type,      XBAR_KIND,   /* A separator bar. */
  230.              TAG_DONE);
  231.  
  232.              LT_New(Handle,
  233.                 LA_Type,      BUTTON_KIND, /* A plain button. */
  234.                 LA_LabelText, "Another button",
  235.                 LA_ID,        22,
  236.              TAG_DONE);
  237.  
  238.              LT_New(Handle,
  239.                 LA_Type,      END_KIND,    /* This ends the current group. */
  240.              TAG_DONE);
  241.           }
  242.  
  243.           if(Window = LT_Build(Handle,
  244.             LAWN_Title,     "Window title",
  245.             LAWN_IDCMP,     IDCMP_CLOSEWINDOW,
  246.             WA_CloseGadget, TRUE,
  247.           TAG_DONE))
  248.           {
  249.               struct IntuiMessage *Message;
  250.               ULONG                MsgQualifier,
  251.                                    MsgClass;
  252.               UWORD                MsgCode;
  253.               struct Gadget       *MsgGadget;
  254.               BOOL                 Done = FALSE;
  255.  
  256.               do
  257.               {
  258.                   WaitPort(Window->UserPort);
  259.  
  260.                   while(Message = GT_GetIMsg(Window->UserPort))
  261.                   {
  262.                      MsgClass     = Message->Class;
  263.                      MsgCode      = Message->Code;
  264.                      MsgQualifier = Message->Qualifier;
  265.                      MsgGadget    = Message->IAddress;
  266.  
  267.                      GT_ReplyIMsg(Message);
  268.  
  269.                      LT_HandleInput(Handle,MsgQualifier,&MsgClass,
  270.                          &MsgCode,&MsgGadget);
  271.  
  272.                      switch(MsgClass)
  273.                      {
  274.                         case IDCMP_CLOSEWINDOW:
  275.  
  276.                             Done = TRUE;
  277.                             break;
  278.  
  279.                         case IDCMP_GADGETUP:
  280.  
  281.                             switch(MsgGadget->GadgetID)
  282.                             {
  283.                                 case 11: printf("First gadget\n");
  284.                                          break;
  285.  
  286.                                 case 22: printf("Second gadget\n");
  287.                                          break;
  288.                             }
  289.  
  290.                             break;
  291.                      }
  292.                   }
  293.               }
  294.               while(!Done);
  295.           }
  296.  
  297.           LT_DeleteHandle(Handle);
  298.        }
  299.  
  300.     The example creates one single group, places a few objects inside,
  301.     calls the layout routine, handles the input and finally cleans
  302.     things up again. This example also shows that you *need* at
  303.     least one group in your tree (to form the root) in order to get
  304.     things to work.
  305.        The input loop requires you to call LT_HandleInput() in order
  306.     to get the user interface code to filter out certain events and
  307.     to update internal information. The data passed in must have
  308.     been processed via the gadtools.library routines. You *must not*
  309.     call LT_HandleInput() before GT_ReplyIMsg() is called since the
  310.     routine may call intuition.library and gadtools.library routines
  311.     which in turn might lead to a system lock-up if the message
  312.     has not been processed yet. The first thing to do after LT_HandleInput()
  313.     has done whatever was necessary to the data you passed in is
  314.     examine the MsgClass variable. The user interface code will
  315.     `fake' certain message events using the variables passed in,
  316.     *do not* use any other data gathered from the original
  317.     IntuiMessage. The MsgClass may include event types you did
  318.     not ask for, i.e. the IDCMP flags of the window opened
  319.     will be set according to the objects you added to the window.
  320.     Also, the IDCMP_IDCMPUPDATE message class will show up for
  321.     certain objects. More on this later in this document.
  322.  
  323.  
  324.     2.4 Setting and getting object attributes
  325.  
  326.     The mechanism to update and query object attributes does not
  327.     exactly match the familiar gadtools.library interface. In
  328.     fact, the routine to change gadget attributes will forward
  329.     the tagitem list passed in to gadtools.library/GT_SetGadgetAttrs().
  330.     On the other hand the routine to query object attributes does
  331.     not work like gadtools.library/GT_GetGadgetAttrs(). The
  332.     user interface code assumes that all objects it can handle and
  333.     create posess certain attributes unique to the type of the
  334.     object in question. For example, the unique attribute of a
  335.     STRING_KIND object would be a pointer to the string it
  336.     `contains'. The unique attribute of a SLIDER_KIND object is
  337.     the current slider position. The LT_GetAttributes() routine
  338.     will return this attribute, but also accept a tagitem list
  339.     to fill in for certain special tag values.
  340.  
  341.  
  342.     2.5 Extra data
  343.  
  344.     Once a LayoutHandle has been created the interface code will
  345.     provide you with a number of information concerning the screen
  346.     the handle has been attached to. This information includes
  347.     the DrawInfo structure of the screen, the VisualInfo data
  348.     and the Screen address. This information is read-only.
  349.  
  350.  
  351.     2.6 Menus
  352.  
  353.     With a LayoutHandle available a routine called LT_LayoutMenuTags()
  354.     will create a standard Intuition menu structure via gadtools.library
  355.     which can be passed to LT_Build(). Note that this
  356.     routine does not modify any data passed in, it does neither
  357.     attach the menu created to the LayoutHandle passed in,
  358.     nor does it change the NewMenu table.
  359.  
  360.  
  361.     2.7 Localization
  362.  
  363.     All object and menu creation routines support localization via
  364.     a Hook callback interface, i.e. you can pass a pointer to an
  365.     initialized Hook structure to LT_CreateHandleTags() which will
  366.     later be used to supply label and list text for objects
  367.     created. The Hook callback routine is called in the following
  368.     fashion:
  369.  
  370.        String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,LONG ID)
  371.          D0                            A0                         A2        A1
  372.  
  373.     Or in other words: a locale string ID is passed in, the routine is supposed
  374.     to look up the string to match this ID and to return it.
  375.  
  376.  
  377.     2.8 Object types to generate IDCMP_IDCMPUPDATE events
  378.  
  379.     Certain objects convey extra information which is merged into the `fake'
  380.     input stream passed to the client calling LT_HandleInput(). These objects
  381.     are:
  382.  
  383.        STRING_KIND
  384.        TEXT_KIND
  385.        PALETTE_KIND
  386.  
  387.           The user pressed the `select' button which belongs
  388.           to this gadget. The MsgGadget pointer indicates the
  389.           STRING_KIND/TEXT_KIND/PALETTE_KIND object the `select'
  390.           button belongs to.
  391.  
  392.        LISTVIEW_KIND
  393.  
  394.           The user double-clicked on an entry. The entry number
  395.           is returned in the MsgCode variable. The MsgGadget
  396.           pointer indicates the LISTVIEW_KIND object the user
  397.           has clicked on.
  398.  
  399.  
  400.     2.9 Keystroke activation
  401.  
  402.     Unless forbidden via the the LA_NoKey tag item the user interface
  403.     code will pick the keyboard shortcuts for all gadgets on its own.
  404.     The currently active global console keymap will be checked at the
  405.     time when LT_Init() is called in order to make sure subsequent
  406.     calls to LT_Build() will use only keys the user can press on
  407.     the keyboard. Double-dead keys are also excluded from the
  408.     table created. This avoids problems with gadget labels such as
  409.     "éééé" which would require the user to hit two keys in a row to
  410.     activate the gadget.
  411.        If the window created happens to feature a close gadget
  412.     pressing the `Esc' key will cause the client to receive
  413.     an IDCMP_CLOSEWINDOW event.
  414.        A single LISTVIEW_KIND object may receive special treatment
  415.     if the LALV_CursorKey tag is used: the user will be able to
  416.     operate the listview using the cursor keys. Note: this
  417.     will also keep the user interface code from choosing a
  418.     special keystroke from the gadget label.
  419.        The user will be able to operate a single BUTTON_KIND
  420.     object using the return key if the LABT_ReturnKey tag is
  421.     used. A recessed frame will be drawn around the button hit
  422.     box to indicate its special status.
  423.        Pressing the Tab key can be bound to operate a cycle or
  424.     mx kind object.
  425.  
  426.     3. Credits
  427.  
  428.     The original design is based upon the user interface layout code used by
  429.     `term' 3.1. I put the first version of the layout routines together back
  430.     in Summer 1993 when I wanted to write the follow-up to `term' v3.4.
  431.  
  432.     Martin Taillefer rewrote large parts of the code, added new routines and
  433.     generally improved the performance of the layout process. I owe Martin
  434.     much for the ideas he put into the library.
  435.  
  436.     Kai Iske, Christoph Feck, Stefan Becker, Michael Barsoom, Sven Stullich
  437.     and Mark Ritter helped to iron out the remaining bugs and piled up bug
  438.     reports and enhancement requests.
  439.  
  440. gtlayout.library/--version--                     gtlayout.library/--version--
  441.  
  442.    NOTES
  443.     This document describes gtlayout.library v5.12 or higher. Do not assume that
  444.     previous library releases support the same features.
  445.  
  446. gtlayout.library/LT_Activate                     gtlayout.library/LT_Activate
  447.  
  448.    NAME
  449.     LT_Activate -- Activate a string type gadget.
  450.  
  451.    SYNOPSIS
  452.     LT_Activate(Handle,ID);
  453.                   A0   D0
  454.  
  455.     VOID LT_Activate(LayoutHandle *,LONG);
  456.  
  457.    FUNCTION
  458.     The equivalent to intuition.library/ActivateGadget().
  459.  
  460.    INPUTS
  461.     Handle - Pointer to LayoutHandle structure.
  462.  
  463.     ID - ID of Gadget to activate.
  464.  
  465.    RESULT
  466.     none
  467.  
  468.    SEE ALSO
  469.     intuition.library/ActivateGadget
  470.  
  471. gtlayout.library/LT_BeginRefresh             gtlayout.library/LT_BeginRefresh
  472.  
  473.    NAME
  474.     LT_BeginRefresh -- Optimized window refreshing
  475.  
  476.    SYNOPSIS
  477.     LT_BeginRefresh(Handle)
  478.                       A0
  479.  
  480.    FUNCTION
  481.     If you wish to handle window refreshing all on your own, you
  482.     might want to use the LT_BeginRefresh...LT_EndRefresh pair
  483.     in your program. By default the user interface layout engine
  484.     will automatically intercept IDCMP_REFRESHWINDOW events and
  485.     react to them accordingly.
  486.  
  487.    INPUTS
  488.     Handle - Pointer to a LayoutHandle structure.
  489.  
  490.    RESULT
  491.     none
  492.  
  493.    SEE ALSO
  494.     intuition.library/BeginRefresh
  495.     intuition.library/EndRefresh
  496.     gtlayout.library/LT_EndRefresh
  497.  
  498. gtlayout.library/LT_BuildA                         gtlayout.library/LT_BuildA
  499.  
  500.    NAME
  501.     LT_BuildA -- turn the user interface specs into a window
  502.                  and gadgets.
  503.  
  504.    SYNOPSIS
  505.     Window = LT_BuildA(Handle,Tags);
  506.       D0                 A0    A1
  507.  
  508.     struct Window *LT_BuildA(LayoutHandle *,struct TagItem *);
  509.  
  510.     Window = LT_Build(Handle,...);
  511.  
  512.     struct Window *LT_Build(LayoutHandle *,...);
  513.  
  514.    FUNCTION
  515.     This is the big one. After building up a user interface specification
  516.     using LT_NewA() a call to LT_BuildA() will finally lay out the single
  517.     user interface elements, open a window and put the gadgets, etc.
  518.     inside.
  519.  
  520.     The code tries to fit all the gadgets into the window, but if it
  521.     runs out of space it will fall back to a different font and
  522.     rescale the user interface objects to match it. It will first
  523.     fall back onto the system default font. If unsuccessful it will
  524.     as a last resort try to use topaz.font/8.
  525.  
  526.     To make it easier to distinguish between different handles that
  527.     share the same Window->UserPort, the Window->UserData pointer
  528.     will point to the LayoutHandle that created it (V13).
  529.  
  530.         NOTE: Earlier library releases did not support this feature,
  531.             so be prepared to deal with Window->UserData == NULL.
  532.  
  533.    INPUTS
  534.     Handle - Pointer to a LayoutHandle structure.
  535.  
  536.     Tags - Pointer to TagItem list controlling window
  537.         and layout attributes.
  538.  
  539.  
  540.     All the tag values given are passed straight away to OpenWindowTags(),
  541.     see intuition.doc for more information.
  542.  
  543.     In addition to this a number of private tag values are supported:
  544.  
  545.     LAWN_Menu (struct Menu *) - The menu to attach to the window. The
  546.         IDCMP flags will be updated to include IDCMP_MENUPICK if this
  547.         tag is used.
  548.  
  549.     LAWN_MenuTemplate (struct NewMenu *) - A list of filled-in
  550.         NewMenu structures which will get passed straight through
  551.         to LT_NewMenuTemplate(). If a menu could be created, it will
  552.         be attached to the window. LT_DeleteHandle() will then later
  553.         automatically dispose of the menu. Please note that the window
  554.         may fail to open due to the menu layout going wrong. Separate
  555.         calls to LT_NewMenuTemplate() and LT_Build() may be a better
  556.         approach since it is easier to find out which process went
  557.         wrong. You will find a pointer to the menu attached to the
  558.         LayoutHandle in LayoutHandle->Menu. Please note that this
  559.         entry only exists in LayoutHandles created by gtlayout.library
  560.         v13 or higher. (V13)
  561.  
  562.             NOTE: This tag effectively overrides LAWN_Menu.
  563.  
  564.     LAWN_MenuTags (struct TagItem *) - A list of TagItems which
  565.         will get passed straight through to LT_NewMenuTagList().
  566.         Even if you don't ask for it, LT_Build() will pass
  567.         "LAMN_Handle,<Handle>" in for you, so any additional tags
  568.         specifying screen, fonts, etc. will be overridden. If a menu
  569.         could be created, it will be attached to the window.
  570.         LT_DeleteHandle() will then later automatically dispose of the
  571.         menu. Please note that the window may fail to open due to the
  572.         menu layout going wrong. Separate calls to LT_NewMenuTagList()
  573.         and LT_Build() may be a better approach since it is easier to
  574.         find out which process went wrong. You will find a pointer to the
  575.         menu attached to the LayoutHandle in LayoutHandle->Menu. Please note
  576.         that this entry only exists in LayoutHandles created by
  577.         gtlayout.library v13 or higher. (V13)
  578.  
  579.             NOTE: This tag effectively overrides LAWN_Menu and has
  580.                   precedence over LAWN_MenuTemplate.
  581.  
  582.     LAWN_UserPort (struct MsgPort *) - The MsgPort to use as the
  583.         window user port. The MsgPort will be attached using the
  584.         common ModifyIDCMP() method, closing the window will
  585.         first remove and reply all pending messages at this port.
  586.  
  587.     LAWN_Left (LONG) - The left edge position the window is to use.
  588.         This effectively overrides any horizontal alignment flags.
  589.  
  590.             NOTE: the code may choose to ignore this value if it finds
  591.                 that the window will not fit onto the screen unless
  592.                 the left edge position is changed.
  593.  
  594.     LAWN_Top (LONG) - The top edge position the window is to use.
  595.         This effectively overrides any vertical alignment flags.
  596.  
  597.             NOTE: the code may choose to ignore this value if it finds
  598.                 that the window will not fit onto the screen unless
  599.                 the top edge position is changed.
  600.  
  601.     LAWN_Zoom (BOOL) - Adds a zoom gadget to the window. Clicking
  602.         on this gadget will cause the window to shrink/zoom back
  603.         to its original position. This differs from the WA_Zoom
  604.         tag behaviour. When the window zooms back to its original
  605.         position the gadgets are automatically refreshed.
  606.         Default: FALSE
  607.  
  608.     LAWN_MaxPen (LONG) - The maximum rendering pen index your code
  609.         will use. Since you are -- with some restrictions -- allowed
  610.         to render into the window created you may want to avoid
  611.         silly side effects if drawing images or other colourful
  612.         textures which do not share the common user interface colours.
  613.         By default the layout code will change the maximum rendering
  614.         pen number for the window to include only the user interface
  615.         pen colours. This can, but need not disturb your own private
  616.         window rendering.
  617.         Look up graphics.library/SetMaxPen for more information.
  618.         Default: determined by looking up Screen->DrawInfo.dri_Pens
  619.  
  620.     LAWN_BelowMouse (BOOL) - This instructs the layout routine to
  621.         centre the window created -- if possible -- below the
  622.         mouse pointer. This effectively ignores any left edge,
  623.         top edge or alignment settings.
  624.         Default: FALSE
  625.  
  626.     LAWN_MoveToWindow (BOOL) - When the window is finally open the
  627.         user interface code will try to make sure the entire window
  628.         is visible on the screen, this may involve moving the
  629.         currently visible portion of an autoscrolling screen.
  630.         Default: TRUE
  631.  
  632.     LAWN_AutoRefresh (BOOL) - Handle IDCMP_REFRESHWINDOW events
  633.         automatically.
  634.         Default: TRUE
  635.  
  636.     LAWN_HelpHook (struct Hook *) - Hook code to invoke when the user
  637.         presses the "Help" key. See gtlayout.h for more information.
  638.         Default: NULL
  639.  
  640.     LAWN_Parent (struct Window *) - Parent window to centre the child
  641.         window in.
  642.         Default: NULL
  643.  
  644.     LAWN_BlockParent (BOOL) - Lock the parent window via LT_LockWindow()
  645.         until the child window is closed.
  646.  
  647.             NOTE: requires LAWN_Parent attribute.
  648.  
  649.         Default: FALSE
  650.  
  651.     LAWN_SmartZoom (BOOL) - Attach a zoom gadget to the window created.
  652.         When in zoomed state, the window will be as small as possible,
  653.         showing only the window title and window gadgets:
  654.  
  655.             NOTE: this tag implies LAWN_Zoom,TRUE
  656.  
  657.         Default: FALSE
  658.  
  659.     LAWN_Title (STRPTR) - The window title to use. Use this tag in
  660.         place of WA_Title or you will break the layout code.
  661.         Default: no title
  662.  
  663.     LAWN_Bounds (struct IBox *) - Bounds to centre the window in.
  664.         Default: NULL
  665.  
  666.     LAWN_ExtraWidth (LONG) - Extra width to add into the calculation
  667.         when opening the window.
  668.         Default: 0
  669.  
  670.     LAWN_ExtraHeight (LONG) - Extra height to add into the calculation
  671.         when opening the window.
  672.         Default: 0
  673.  
  674.     LAWN_IDCMP (ULONG) - Use this tag in place of WA_IDCMP or you
  675.         will break the object handling code.
  676.  
  677.     LAWN_AlignWindow (UWORD) - Alignment information for the window, must
  678.         be a mask made from the following bit values:
  679.  
  680.             ALIGNF_RIGHT - Align to screen right edge
  681.             ALIGNF_LEFT - Align to screen left edge
  682.             ALIGNF_TOP - Align to screen top edge
  683.             ALIGNF_BOTTOM - Align to screen bottom edge
  684.  
  685.         Unless forbidden (such as by passing ALIGNF_RIGHT|ALIGNF_TOP)
  686.         the window will be centered horizontally and/or vertically.
  687.  
  688.     LAWN_FlushLeft (BOOL) - Add no horizontal space surrounding the
  689.         objects the windows will hold. (V10)
  690.  
  691.     LAWN_FlushTop (BOOL) - Add no vertical space surrounding the
  692.         objects the windows will hold. (V10)
  693.  
  694.     LAWN_Show (BOOL) - Make the window visible when it is opened;
  695.         this may involve depth-arranging screens. (V10)
  696.            Default: FALSE
  697.  
  698.     LAWN_NoInitialRefresh (BOOL) - If set to TRUE, adds the
  699.         gadgets, but does not draw the window imagery. You need
  700.         to draw them later by calling gtlayout.library/LT_Refresh.
  701.         Default: FALSE
  702.  
  703.     LAWN_LimitWidth (UWORD) - Limit the width of the window to this
  704.         value. (V35)
  705.  
  706.     LAWN_LimitHeight (UWORD) - Limit the height of the window to this
  707.         value. (V35)
  708.  
  709.     LAWN_UserData (APTR) - Store this pointer with the Window information.
  710.         you can later retrieve it with the LT_GetWindowUserData()
  711.         call (V39).
  712.  
  713.    RESULT
  714.     Window - Pointer to a Window structure.
  715.  
  716.    SEE ALSO
  717.        gtlayout.library/LT_Refresh
  718.        gtlayout.library/LT_GetWindowUserData
  719.        intuition.library/OpenWindow
  720.        intuition.library/OpenWindowTagList
  721.  
  722. gtlayout.library/LT_CatchUpRefresh         gtlayout.library/LT_CatchUpRefresh
  723.  
  724.    NAME
  725.     LT_CatchUpRefresh -- Repair the display after missing the
  726.                          Window refresh message (V34).
  727.  
  728.    SYNOPSIS
  729.     LT_CatchUpRefresh(Handle)
  730.                         A0
  731.  
  732.     VOID LT_CatchUpRefresh(LayoutHandle *);
  733.  
  734.    FUNCTION
  735.     In case an application missed an IDCMP_REFRESHWINDOW event
  736.     the display may be damaged and in need of repair. This can
  737.     happen if the ASL requester is attached to the window,
  738.     sharing its IDCMP with the window. Any refresh events will then
  739.     go straight to nil. Call this routine if you believe that
  740.     you missed a refresh event. The display will be repaired only
  741.     if it is in need of repair, so there is no harm in calling it
  742.     if not actually necessary.
  743.  
  744.    INPUTS
  745.     Handle - Pointer to a LayoutHandle structure.
  746.  
  747.    RESULT
  748.     none
  749.  
  750.    SEE ALSO
  751.     gtlayout.library/LT_BeginRefresh
  752.     intuition.library/BeginRefresh
  753.     intuition.library/EndRefresh
  754.  
  755. gtlayout.library/LT_CreateHandleTagListtlayout.library/LT_CreateHandleTagList
  756.  
  757.    NAME
  758.     LT_CreateHandleTagList -- Allocate auxilary data required by LT_New()
  759.                               and LT_BuildA().
  760.  
  761.    SYNOPSIS
  762.     Handle = LT_CreateHandleTagList(Screen,Tags);
  763.       D0                              A0    A1
  764.  
  765.     LayoutHandle *LT_CreateHandleTagList(struct Screen *,struct TagItem *);
  766.  
  767.     Handle = LT_CreateHandleTags(Screen,...);
  768.  
  769.     struct LayoutHandle *LT_CreateHandleTags(struct Screen *,...);
  770.  
  771.    FUNCTION
  772.     Memory is allocated, tables are set up and data is collected
  773.     on a screen a user interface is to be opened on. This
  774.     involves calculating the screen font parameters.
  775.  
  776.    INPUTS
  777.     Screen - Pointer to the screen the user interface is to
  778.         use. Passing NULL will cause the default public
  779.         screen to be used.
  780.  
  781.             NOTE: if NULL is passed the default public screen
  782.                 will stay locked until LT_DeleteHandle()
  783.                 is called.
  784.  
  785.     Tags - Tag values to control certain aspects of the
  786.         user interface created.
  787.  
  788.  
  789.     Valid tags include:
  790.  
  791.     LAHN_AutoActivate (BOOL) - Set to TRUE if you want the interface
  792.         to always keep a string gadget active if possible. Hitting
  793.         the return key will then cause the next following string
  794.         gadget to get activated, either cycling through all the
  795.         string gadgets available or stopping at the next string
  796.         gadget to have the LAST_LastGadget attribute set.
  797.         Default: TRUE
  798.  
  799.     LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
  800.         events. (V13)
  801.         Default: TRUE
  802.  
  803.     LAHN_UserData (APTR) - Store user specific data in the
  804.         LayoutHandle->UserData entry.
  805.  
  806.             NOTE: This tag requires gtlayout.library v9 and the
  807.                 corresponding entry in the LayoutHandle exists
  808.                 only under gtlayout.library v9 and up. *NEVER*
  809.                 write to this entry, use LT_SetAttributes()
  810.                 instead.
  811.  
  812.     LAHN_LocaleHook (struct Hook *) - The hook to call when
  813.         locale string IDs are to be mapped to strings. The
  814.         hook function is called with the following parameters:
  815.  
  816.         String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
  817.           D0                            A0                         A2
  818.                           LONG ID)
  819.                                A1
  820.  
  821.         The function is to look up the string associated with the ID
  822.         passed in and return the string.
  823.         Default: no locale hook
  824.  
  825.     LAHN_TextAttr (struct TTextAttr *) - The text font to use when
  826.         creating the gadgets and objects.
  827.         Default: Screen->Font
  828.  
  829.     LAHN_CloningPermitted (BOOL) - If a window will not fit onto the
  830.         screen the user interface is intended for, the layout engine
  831.         will scale the interface data down while stepping down in
  832.         font size. If all this fails, the engine will open a custom
  833.         screen for the window; this process is called "cloning".
  834.         The LAHN_CloningPermitted tag controls whether the engine will
  835.         actually try to open the custom screen or just return NULL
  836.         when LT_Build fails.
  837.         Default: TRUE
  838.  
  839.     LAHN_EditHook (struct Hook *) - You can specify a default string
  840.         gadget editing hook to be used for all following string
  841.         gadgets. Your hook should obey the same rules that apply
  842.         to hooks passed via GTST_EditHook/GTIN_EditHook.
  843.         Default: NULL
  844.  
  845.     LAHN_ExactClone (BOOL) - This tag works in conjunction with the
  846.         LAHN_CloningPermitted tag. By default the layout engine will
  847.         try to replicate only the basic characteristics of the
  848.         screen the window was intended to open on. This may result
  849.         in a screen which uses less colours than the original
  850.         screen. You can force the engine to make an almost exact
  851.         clone of the original screen by passing the LAHN_ExactClone
  852.         tag with a value of TRUE.
  853.         Default: FALSE
  854.  
  855.     LAHN_MenuGlyphs (BOOL) - This tag will make the layout engine
  856.         fill in the AmigaGlyph and CheckGlyph entries of the
  857.         LayoutHandle if running under Kickstart 3.0 or higher.
  858.         The corresponding images will be scaled to fit the actual
  859.         screen aspect ratio values and can later be used for
  860.         menu layout.
  861.         Default: FALSE
  862.  
  863.     LAHN_Parent (struct Window *) - You can pass a pointer to the
  864.         parent window of the window you intend to open using
  865.         the user interface layout engine. The new window will
  866.         open inside the boundaries of the parent window. If the
  867.         size does not fit, it will be opened centered over the
  868.         parent window.
  869.         Default: NULL
  870.  
  871.     LAHN_BlockParent (BOOL) - This tag works in conjunction with the
  872.         LAHN_Parent tag. If in effect, will block the parent window
  873.         via LT_LockWindow until the new window is closed, after
  874.         which the parent window is unlocked again.
  875.         Default: FALSE
  876.  
  877.     LAHN_SimpleClone (BOOL) - This tag works in conjunction with the
  878.         LAHN_CloningPermitted tag. It will make the layout engine
  879.         forget most information about the original screen the
  880.         user interface was intended for. In short, it will open a
  881.         simple default screen for the interface.
  882.         Default: FALSE
  883.  
  884.     LAHN_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
  885.         of with LT_DeleteHandle() all variables maintained by the
  886.         input handling code will be flushed. For example, if you
  887.         would use the LA_STRPTR tag for STRING_KIND objects the
  888.         last string gadget contents would be copied into the buffer
  889.         pointed to by LA_STRPTR. If you do not want to use this
  890.         feature, disable it with "LAHN_ExitFlush,FALSE". (V9)
  891.         Default: TRUE
  892.  
  893.     LAHN_NoKeys (BOOL) - Use TRUE to tell the library not to pick
  894.         keyboard shortcuts all on its own. This works like calling
  895.         LT_New() for all objects with "LA_NoKey,TRUE,". (V26)
  896.  
  897.     LAHN_PubScreen (struct Screen *) - Pointer to public screen
  898.         window is to open on. Must be locked and open until you call
  899.         LT_Built().
  900.  
  901.     LAHN_PubScreenName (STRPTR) - Name of public screen to open window
  902.         on. The library will try to lock the named screen as soon as
  903.         you call LT_CreateHandle.
  904.  
  905.     LAHN_PubScreenFallBack (BOOL) - If the named public screen cannot
  906.         be found and you ask for it, the library will lock the default
  907.         public screen (default: TRUE).
  908.  
  909.    RESULT
  910.     Handle - Pointer to a LayoutHandle structure.
  911.  
  912. gtlayout.library/LT_DeleteHandle             gtlayout.library/LT_DeleteHandle
  913.  
  914.    NAME
  915.     LT_DeleteHandle -- Release storage space allocated by
  916.                        LT_CreateHandleTagList, closing windows,
  917.                        removing gadgets, etc.
  918.  
  919.    SYNOPSIS
  920.     LT_DeleteHandle(Handle);
  921.                       A0
  922.  
  923.     VOID LT_DeleteHandle(LayoutHandle *);
  924.  
  925.    FUNCTION
  926.     Windows and gadgets created by LT_CreateHandleTagList()
  927.     are removed, any associated memory is deallocated.
  928.  
  929.    INPUTS
  930.     Handle - Pointer to a LayoutHandle structure created
  931.         by LT_CreateHandleTaglist(). Passing NULL is
  932.         harmless.
  933.  
  934.    RESULT
  935.     none
  936.  
  937.    SEE ALSO
  938.     gtlayout.library/CreateHandleTagList
  939.  
  940. gtlayout.library/LT_DeleteWindowLock     gtlayout.library/LT_DeleteWindowLock
  941.  
  942.    NAME
  943.     LT_DeleteWindowLock -- Remove all locks from a window
  944.  
  945.    SYNOPSIS
  946.     LT_DeleteWindowLock(Window);
  947.                           A0
  948.  
  949.     VOID LT_DeleteWindowLock(struct Window *);
  950.  
  951.    FUNCTION
  952.     Before closing a locked window you should call this routine
  953.     which will remove all outstanding locks from it.
  954.  
  955.    INPUTS
  956.     Window - Pointer to window structure; passing NULL is
  957.     harmless.
  958.  
  959.    RESULT
  960.     none
  961.  
  962. gtlayout.library/LT_DisposeMenu               gtlayout.library/LT_DisposeMenu
  963.  
  964.    NAME
  965.     LT_DisposeMenu -- Release storage space allocated by
  966.                       LT_NewMenuTemplate or LT_NewMenuTagList (V11)
  967.  
  968.    SYNOPSIS
  969.     LT_DisposeMenu(Menu)
  970.                     A0
  971.  
  972.     VOID LT_DisposeMenu(struct Menu *);
  973.  
  974.    FUNCTION
  975.     Menus and MenuItems allocated by LT_NewMenuTemplate or
  976.     LT_NewMenuTagList are deallocated.
  977.  
  978.    INPUTS
  979.     Menu - Pointer to Menu structure as returned by
  980.         LT_NewMenuTemplate or LT_NewMenuTagList. Passing
  981.         NULL is harmless.
  982.  
  983.    RESULT
  984.     none
  985.  
  986.    SEE ALSO
  987.     gtlayout.library/LT_NewMenuTagList
  988.     gtlayout.library/LT_NewMenuTemplate
  989.  
  990. gtlayout.library/LT_EndGroup                     gtlayout.library/LT_EndGroup
  991.  
  992.    NAME
  993.     LT_EndGroup -- end a group declaration.
  994.  
  995.    SYNOPSIS
  996.     LT_EndGroup(Handle);
  997.                  A0
  998.  
  999.     VOID LT_EndGroup(LayoutHandle *);
  1000.  
  1001.    FUNCTION
  1002.       This is just a short form of
  1003.  
  1004.            LT_New(Handle,
  1005.                LA_Type, END_KIND,
  1006.            TAG_DONE);
  1007.  
  1008.       It helps to save (some) space.
  1009.  
  1010.    INPUTS
  1011.         Handle - Pointer to LayoutHandle.
  1012.  
  1013.    RESULT
  1014.     none
  1015.  
  1016.    SEE ALSO
  1017.     gtlayout.library/LT_New
  1018.  
  1019. gtlayout.library/LT_EndRefresh                 gtlayout.library/LT_EndRefresh
  1020.  
  1021.    NAME
  1022.     LT_EndRefresh -- Optimized window refreshing
  1023.  
  1024.    SYNOPSIS
  1025.     LT_EndRefresh(Handle)
  1026.                     A0
  1027.  
  1028.     VOID LT_EndRefresh(LayoutHandle *);
  1029.  
  1030.    FUNCTION
  1031.     If you wish to handle window refreshing all on your own, you
  1032.     might want to use the LT_BeginRefresh...LT_EndRefresh pair
  1033.     in your program. By default the user interface layout engine
  1034.     will automatically intercept IDCMP_REFRESHWINDOW events and
  1035.     react to them accordingly.
  1036.  
  1037.    INPUTS
  1038.     Handle - Pointer to a LayoutHandle structure.
  1039.  
  1040.    RESULT
  1041.     none
  1042.  
  1043.    SEE ALSO
  1044.     gtlayout.library/LT_BeginRefresh
  1045.     intuition.library/BeginRefresh
  1046.     intuition.library/EndRefresh
  1047.  
  1048. gtlayout.library/LT_Exit                             gtlayout.library/LT_Exit
  1049.  
  1050.    NAME
  1051.     LT_Exit -- Clean up user interface allocations
  1052.  
  1053.    SYNOPSIS
  1054.     LT_Exit();
  1055.  
  1056.     VOID LT_Exit(VOID);
  1057.  
  1058.    FUNCTION
  1059.     When you are finished with user interface creation and
  1060.     do not not need the code any more you should call this
  1061.     routine. It will free all the memory allocated by
  1062.     LT_Init(), close libraries, etc.
  1063.  
  1064.    INPUTS
  1065.     none
  1066.  
  1067.    RESULT
  1068.     none
  1069.  
  1070.    NOTES
  1071.     This function is not present in the shared library, only
  1072.     in the link library. You need not and cannot invoke it in
  1073.     the shared library.
  1074.  
  1075.    SEE ALSO
  1076.     gtlayout.library/LT_Init
  1077.  
  1078. gtlayout.library/LT_FindMenuCommand       gtlayout.library/LT_FindMenuCommand
  1079.  
  1080.    NAME
  1081.     LT_FindMenuCommand -- Get the menu/submenu item associated
  1082.                           with a rawkey event (V11)
  1083.  
  1084.    SYNOPSIS
  1085.     Item = LT_FindMenuCommand(Menu,Code,Qualifier,Gadget)
  1086.      D0                        A0  D0       D0      A1
  1087.  
  1088.     struct MenuItem *LT_FindMenuCommand(struct Menu *,
  1089.  
  1090.                          UWORD,ULONG,struct Gadget *);
  1091.  
  1092.    FUNCTION
  1093.     With the IntuiMessage data copied from a type IDCMP_RAWKEY message
  1094.     tries to find the MenuItem the event referred to.
  1095.  
  1096.    INPUTS
  1097.     Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1098.  
  1099.     Code - Value copied from IntuiMessage->Code
  1100.  
  1101.     Qualifier - Value copied from IntuiMessage->Qualifier
  1102.  
  1103.     Gadget - Value copied from IntuiMessage->IAddress
  1104.  
  1105.    RESULT
  1106.     Item - Pointer to the struct MenuItem * in question or NULL
  1107.         if none could be found
  1108.  
  1109.    SEE ALSO
  1110.     gtlayout.library/LT_NewMenuTagList
  1111.  
  1112. gtlayout.library/LT_GetAttributesA         gtlayout.library/LT_GetAttributesA
  1113.  
  1114.    NAME
  1115.     LT_GetAttributesA -- Inquire information on a gadget.
  1116.  
  1117.    SYNOPSIS
  1118.     Value = LT_GetAttributesA(Handle,ID,Tags);
  1119.       D0                        A0   D0  A1
  1120.  
  1121.     LONG LT_GetAttributesA(LayoutHandle *,LONG ID,struct TagItem *);
  1122.  
  1123.     Value = LT_GetAttributes(Handle,ID,...);
  1124.  
  1125.     LONG LT_GetAttributes(LayoutHandle *,LONG ID,...);
  1126.  
  1127.    FUNCTION
  1128.     All objects created by the user interface layout code posess
  1129.     certain unique properties. The LT_GetAttributes() function will
  1130.     will inquire this information and return it. The implementation
  1131.     differs from gadtools.library/GT_GetGadgetAttrs in that you
  1132.     can inquire only a small subset of the object properties possible
  1133.     via the taglist passed in.
  1134.  
  1135.    INPUTS
  1136.     Handle - Pointer to LayoutHandle structure.
  1137.  
  1138.     ID - ID number of the object to inquire information about. This
  1139.         is the same value you passed via LA_ID to LT_New() when
  1140.         you created this object.
  1141.  
  1142.     Tags - TagItem list to receive information about the object
  1143.         in question.
  1144.  
  1145.  
  1146.     LA_Left (LONG *) - Left edge of object.
  1147.  
  1148.     LA_Top (LONG *) - Top edge of object.
  1149.  
  1150.     LA_Width (LONG *) - Width of object.
  1151.  
  1152.     LA_Height (LONG *) - Height of object.
  1153.  
  1154.     LA_Chars (LONG *) - Width of object measured in character
  1155.         widths. (V9)
  1156.  
  1157.     LA_Lines (LONG *) - Height of object measured in character
  1158.         heights. (V9)
  1159.  
  1160.     LA_LabelLeft (LONG *) - Left edge of label text. (V9)
  1161.  
  1162.     LA_LabelTop (LONG *) - Top edge of label text. (V9)
  1163.  
  1164.     LABO_Object (Object *) - Returns a pointer to the BOOPSI object
  1165.         the BOOPSI_KIND object is based upon. (V10)
  1166.  
  1167.             NOTE: Don't unlink the object or dispose of it or
  1168.                 terrible things are bound to happen.
  1169.  
  1170.     LAST_CursorPosition (LONG *) - Current position of the cursor
  1171.         in STRING_KIND and FRACTION_KIND objects. (V
  1172.  
  1173.    RESULT
  1174.     The result depends on the object type:
  1175.  
  1176.         VERTICAL_KIND:
  1177.         HORIZONTAL_KIND:
  1178.  
  1179.             active page
  1180.  
  1181.         SCROLLER_KIND:
  1182.  
  1183.             current GTSC_Top value
  1184.  
  1185.         TAPEDECK_KIND:
  1186.  
  1187.             current LATD_Pressed value
  1188.  
  1189.         LEVEL_KIND:
  1190.  
  1191.             current LAVL_Level state
  1192.  
  1193.         CHECKBOX_KIND:
  1194.  
  1195.             current GTCB_Checked state
  1196.  
  1197.         LISTVIEW_KIND:
  1198.  
  1199.             current GTLV_Selected state
  1200.  
  1201.         MX_KIND:
  1202.  
  1203.             current GTMX_Active state
  1204.  
  1205.         CYCLE_KIND:
  1206.  
  1207.             current GTCY_Active state
  1208.  
  1209.         POPUP_KIND:
  1210.  
  1211.             current LAPU_Active state
  1212.  
  1213.         TAB_KIND:
  1214.  
  1215.             current LATB_Active state
  1216.  
  1217.         PALETTE_KIND:
  1218.  
  1219.             current GTPA_Color state
  1220.  
  1221.         SLIDER_KIND:
  1222.  
  1223.             current GTSL_Level state
  1224.  
  1225.         GAUGE_KIND:
  1226.  
  1227.             current LAGA_Percent state
  1228.  
  1229.         STRING_KIND:
  1230.  
  1231.             pointer to current string
  1232.  
  1233.         PASSWORD_KIND:
  1234.  
  1235.             pointer to current string
  1236.  
  1237.         INTEGER_KIND:
  1238.  
  1239.             number currently entered
  1240.  
  1241.         BOOPSI_KIND:
  1242.  
  1243.             whatever the object thinks is its
  1244.             current value
  1245.  
  1246. gtlayout.library/LT_GetCode                       gtlayout.library/LT_GetCode
  1247.  
  1248.    NAME
  1249.     LT_GetCode -- Easy raw key event to ANSI conversion.
  1250.  
  1251.    SYNOPSIS
  1252.     Key = LT_GetCode(Qualifier,Class,Code,Gadget);
  1253.      D0                  D0     D1    D2    A0
  1254.  
  1255.     LONG LT_GetCode(ULONG,ULONG,UWORD,struct Gadget *);
  1256.  
  1257.    FUNCTION
  1258.     The user interface layout engine can convert IDCMP_RAWKEY
  1259.     events into ANSI codes. Pass in the data you copied from
  1260.     the IntuiMessage here.
  1261.  
  1262.    INPUTS
  1263.     Qualifier - Copied from IntuiMessage->Qualifier
  1264.  
  1265.     Class - Copied from IntuiMessage->Class
  1266.  
  1267.     Code - Copied from IntuiMessage->Code
  1268.  
  1269.     Gadget - Copied from IntuiMessage->IAddress
  1270.  
  1271.    RESULT
  1272.     Key - ANSI code generated from the input data
  1273.         or -1 if no such code was to be generated.
  1274.  
  1275. gtlayout.library/LT_GetIMsg                       gtlayout.library/LT_GetIMsg
  1276.  
  1277.    NAME
  1278.     LT_GetIMsg -- Retrieve the next pending IntuiMessage
  1279.                   from the window associated with a
  1280.                   LayoutHandle.
  1281.  
  1282.    SYNOPSIS
  1283.     IntuiMessage = LT_GetIMsg(Handle);
  1284.          D0                     A0
  1285.  
  1286.     struct IntuiMessage *LT_GetIMsg(LayoutHandle *);
  1287.  
  1288.    FUNCTION
  1289.     This routine will handle most of the input loop for
  1290.     you. Just pass the pointer to the layout handle in,
  1291.     check if the result code is non-null, copy the data
  1292.     you need and reply the message via LT_ReplyIMsg().
  1293.  
  1294.     You will still need to wait for new input, as LT_GetIMsg
  1295.     will poll the MsgPort of the window.
  1296.  
  1297.     LT_GetIMsg() will try its best to distinguish between
  1298.     different LayoutHandles sharing the same Window->UserPort.
  1299.     If it finds that the window the message was sent to is
  1300.     using a different LayoutHandle, it will switch to using
  1301.     this handle (V13).
  1302.  
  1303.    INPUTS
  1304.     Handle - Pointer to LayoutHandle structure
  1305.  
  1306.    RESULT
  1307.     IntuiMessage - Pointer to IntuiMessage structure
  1308.  
  1309.    NOTES
  1310.     You *must not* make any assumptions about the contents
  1311.     of the IntuiMessage structure except for the following
  1312.     entries:
  1313.  
  1314.        Class
  1315.        Code
  1316.        Qualifier
  1317.        IAddress
  1318.  
  1319.     When finished, you must dispose the IntuiMessage via
  1320.     LT_ReplyIMsg or memory will be lost which can never
  1321.     be reclaimed.
  1322.  
  1323.     DO NOT CALL LT_HandleInput() ON THE DATA YOU RECEIVE
  1324.     FROM LT_GetIMsg() AS LT_GetIMsg() ALREADY DOES ALL THE
  1325.     MAGIC LT_HandleInput() OTHERWISE WOULD NEED TO DO!
  1326.     IF YOU STILL DO CALL LT_HandleInput() ON THE DATA YOU
  1327.     WILL RECEIVE `GHOST' EVENTS.
  1328.  
  1329.    SEE ALSO
  1330.     gtlayout.library/LT_ReplyIMsg
  1331.  
  1332. gtlayout.library/LT_GetMenuItem               gtlayout.library/LT_GetMenuItem
  1333.  
  1334.    NAME
  1335.     LT_GetMenuItem -- Get the menu/submenu item associated with an ID (V11)
  1336.  
  1337.    SYNOPSIS
  1338.     Item = LT_GetMenuItem(Menu,ID)
  1339.      D0                    A0  D0
  1340.  
  1341.     struct MenuItem *LT_GetMenuItem(struct Menu *,ULONG);
  1342.  
  1343.    FUNCTION
  1344.     This routine scans through all menu items associated with the
  1345.     menu and returns a pointer to the item associated with the
  1346.     given ID value.
  1347.  
  1348.    INPUTS
  1349.     Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1350.  
  1351.     ID - Unique ID of the item to find.
  1352.  
  1353.    RESULT
  1354.     Item - Pointer to the struct MenuItem * in question or NULL
  1355.         if none could be found
  1356.  
  1357.    SEE ALSO
  1358.     gtlayout.library/LT_NewMenuTagList
  1359.  
  1360. gtlayout.library/LT_GetWindowUserData   gtlayout.library/LT_GetWindowUserData
  1361.  
  1362.    NAME
  1363.     LT_GetWindowUserData -- Obtain user data information associated
  1364.         with a Window created by gtlayout.library/LT_Build (V39).
  1365.  
  1366.    SYNOPSIS
  1367.     Data = LT_GetWindowUserData(Window,DefaultValue);
  1368.       D0                         A0        A1
  1369.  
  1370.     APTR LT_GetWindowUserData(struct Window *,APTR);
  1371.  
  1372.    FUNCTION
  1373.     You can tell the build process to store user data with the Window
  1374.     it creates. This can be used as a replacement for the Window->UserData
  1375.     pointer information which gtlayout.library uses for itself. If the
  1376.     Window you pass to this routine was created by gtlayout.library/LT_Build
  1377.     you will receive the user data pointer you passed in, otherwise the
  1378.     given default value will be returned.
  1379.  
  1380.    INPUTS
  1381.     Window - Pointer to a Window created by gtlayout.library/LT_Build
  1382.  
  1383.    RESULT
  1384.     Data - The user data pointer you provided for gtlayout.library/LT_Build
  1385.         with the LAWN_UserData tag or the default value if no such pointer
  1386.         was provided or this Window was not created by
  1387.         gtlayout.library/LT_Build.
  1388.  
  1389.     DefaultValue - If the window was not created by gtlayout.library/LT_Build
  1390.         this is the value you will receive as the function result.
  1391.  
  1392.    SEE ALSO
  1393.        gtlayout.library/LT_Build
  1394.  
  1395. gtlayout.library/LT_HandleInput               gtlayout.library/LT_HandleInput
  1396.  
  1397.    NAME
  1398.     LT_HandleInput -- Filter IntuiMessage data.
  1399.  
  1400.    SYNOPSIS
  1401.     LT_HandleInput(Handle,Qualifier,Class,Code,Gadget);
  1402.                      A0      D0      A1    A2    A3
  1403.  
  1404.     VOID LT_HandleInput(LayoutHandle *,ULONG,ULONG *,
  1405.                         UWORD *,struct Gadget **);
  1406.  
  1407.    FUNCTION
  1408.     In order to keep track of user interface actions, such as
  1409.     keys getting pressed, sliders getting moved, etc. your
  1410.     code is to call LT_HandleInput() with data copied from the
  1411.     IntuiMessage it has just received and replied.
  1412.  
  1413.    INPUTS
  1414.     Handle - Pointer to a LayoutHandle structure.
  1415.  
  1416.     Qualifier - The Qualifier value copied from the
  1417.         IntuiMessage structure.
  1418.  
  1419.     Class - Pointer to the ULONG variable which holds the
  1420.         value copied from the Class entry of the
  1421.         IntuiMessage structure.
  1422.  
  1423.     Code - Pointer to the UWORD variable which holds the
  1424.         value copied from the Code entry of the
  1425.         IntuiMessage structure.
  1426.  
  1427.     Gadget - Pointer to the Gadget value copied from the
  1428.         IAddress entry of the IntuiMessage structure.
  1429.  
  1430.    RESULT
  1431.     none
  1432.  
  1433.    EXAMPLE
  1434.     struct IntuiMessage *IntuiMessage;
  1435.     ULONG Qualifier,Class;
  1436.     UWORD Code;
  1437.     struct Gadget *Gadget;
  1438.  
  1439.     for(;;)
  1440.     {
  1441.         WaitPort(Window->UserPort);
  1442.  
  1443.         while(IntuiMessage = GT_GetIMsg(Window->UserPort))
  1444.         {
  1445.             Class = IntuiMessage->Class;
  1446.             Code = IntuiMessage->Code;
  1447.             Qualifier = IntuiMessage->Qualifier;
  1448.             Gadget = IntuiMessage->Gadget;
  1449.  
  1450.             GT_ReplyIMsg(IntuiMessage);
  1451.  
  1452.             LT_HandleInput(Handle,Qualifier,&Class,&Code,&Gadget);
  1453.         }
  1454.     }
  1455.  
  1456.    NOTES
  1457.     For BOOPSI_KIND objects keystroke activation may lead to
  1458.     unexpected results. Your application will hear a IDCMP_GADGETUP
  1459.     event, the IntuiMessage->Code value will hold the ANSI key
  1460.     code of the key the user pressed.
  1461.  
  1462.     Do not call this routine before you have actually
  1463.     replied the IntuiMessage received or weird things
  1464.     may happen. This is not a suggestion, it's a threat.
  1465.  
  1466. gtlayout.library/LT_Init                             gtlayout.library/LT_Init
  1467.  
  1468.    NAME
  1469.     LT_Init -- Initialize user interface code.
  1470.  
  1471.    SYNOPSIS
  1472.     LT_Init();
  1473.  
  1474.     VOID LT_Init(VOID);
  1475.  
  1476.    FUNCTION
  1477.     You need to initialize the user interface code only once,
  1478.     so it can set up its internals, open libraries, etc.
  1479.     The code has to be initialized before any user interface
  1480.     creation can take place.
  1481.  
  1482.    NOTES
  1483.     This function is not present in the shared library, only
  1484.     in the link library. You need not and cannot invoke it in
  1485.     the shared library.
  1486.  
  1487.    SEE ALSO
  1488.     gtlayout.library/LT_Exit
  1489.  
  1490. gtlayout.library/LT_LabelChars                 gtlayout.library/LT_LabelChars
  1491.  
  1492.    NAME
  1493.     LT_LabelChars -- Calculate the width of a a string
  1494.                      according to the user interface font
  1495.                      associated with a LayoutHandle.
  1496.  
  1497.    SYNOPSIS
  1498.     Length = LT_LabelChars(Handle,Label);
  1499.       D0                     A0    A1
  1500.  
  1501.     LONG LT_LabelChars(struct LayoutHandle *,STRPTR);
  1502.  
  1503.    FUNCTION
  1504.     Calculates the width of a string according to the user
  1505.     interface font used. The width is then converted to a number
  1506.     of characters suitable for using with the LA_Chars tag
  1507.     item when calling LT_New().
  1508.  
  1509.     You can pass multi-line label texts to this routine,
  1510.     it will calculate the maximum length of the single
  1511.     lines. (V12)
  1512.  
  1513.    INPUTS
  1514.     Handle - Pointer to LayoutHandle structure.
  1515.  
  1516.     Label - Pointer to string.
  1517.  
  1518.    RESULT
  1519.     Length - Number of characters that are considered
  1520.         equivalent to the string length in pixels.
  1521.  
  1522. gtlayout.library/LT_LabelWidth                 gtlayout.library/LT_LabelWidth
  1523.  
  1524.    NAME
  1525.     LT_LabelWidth -- Calculate the width of a string according
  1526.                      to the user interface font used.
  1527.  
  1528.    SYNOPSIS
  1529.     Width = LT_LabelWidth(Handle,Label);
  1530.       D0                    A0    A1
  1531.  
  1532.     LONG LT_LabelWidth(LayoutHandle *,STRPTR);
  1533.  
  1534.    FUNCTION
  1535.     This routine calculates the width of strings in
  1536.     terms of pixels according to the user interface
  1537.     font associated with the LayoutHandle.
  1538.  
  1539.     You can pass multi-line label texts to this routine,
  1540.     it will calculate the maximum length of the single
  1541.     lines. (V12)
  1542.  
  1543.    INPUTS
  1544.     Handle - Pointer to LayoutHandle structure.
  1545.  
  1546.    RESULT
  1547.     Width - Width of the text string in pixels.
  1548.  
  1549. gtlayout.library/LT_LayoutMenusA             gtlayout.library/LT_LayoutMenusA
  1550.  
  1551.    NAME
  1552.     LT_LayoutMenusA -- Create a menu according to a template.
  1553.  
  1554.    SYNOPSIS
  1555.     Menu = LT_LayoutMenusA(Handle,Template,Tags);
  1556.      D0                      A0     A1      A2
  1557.  
  1558.     struct Menu *LT_LayoutMenusA(LayoutHandle *,struct NewMenu *,
  1559.  
  1560.         struct TagItem *);
  1561.  
  1562.     Menu = LT_LayoutMenus(Handle,Template,...);
  1563.  
  1564.     struct Menu *LT_LayoutMenus(LayoutHandle *,struct NewMenu *,...);
  1565.  
  1566.    FUNCTION
  1567.     Unlike the corresponding routines in gadtools.library
  1568.     LT_LayoutMenusA() will both create and layout a menu.
  1569.     Also included is locale support.
  1570.  
  1571.    INPUTS
  1572.     Handle - Pointer to LayoutHandle structure.
  1573.  
  1574.     Template - Address of a ready-to-use NewMenu table to
  1575.         create the menu from.
  1576.  
  1577.     Tags - Tagitem list to control menu attributes
  1578.  
  1579.     Tags:
  1580.  
  1581.     LAMN_FirstLabel (LONG) - Locale ID of the first string to
  1582.         use as a menu title/item/subitem label. This tag
  1583.         works in conjunction with LA_LastLabel.
  1584.  
  1585.     LAMN_LastLabel (LONG) - Locale ID of the last string to
  1586.         use as a menu title/item/subitem label. This tag
  1587.         works in conjunction with LA_FirstLabel. The code
  1588.         will loop through FirstLabel..LastLabel and assign
  1589.         the corresponding locale text for each ID to the
  1590.         NewMenu.nm_Label entries. Labels which are already
  1591.         initialized with NM_BARLABEL are skipped.
  1592.  
  1593.     LAMN_LabelTable (LONG *) - Pointer to an array of IDs
  1594.         to use for building the menu labels. This requires
  1595.         that a locale hook is provided with the layout handle.
  1596.         The array is terminated by -1.
  1597.  
  1598.    RESULT
  1599.     Menu - Pointer to a Menu structure. You can free this
  1600.            using gadtools.library/FreeMenus().
  1601.  
  1602. gtlayout.library/LT_LevelWidth                 gtlayout.library/LT_LevelWidth
  1603.  
  1604.    NAME
  1605.     LT_LevelWidth -- Determine the maximum width of a SLIDER_KIND
  1606.                      level string.
  1607.  
  1608.    SYNOPSIS
  1609.     Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
  1610.       D0                    A0        A1         A2     D0  D1    A3
  1611.  
  1612.                               MaxLen,FullCheck);
  1613.                                 A5      D2
  1614.  
  1615.     LONG LT_LevelWidth(LayoutHandle *,STRPTR,
  1616.                        LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
  1617.                        LONG *,BOOL);
  1618.  
  1619.    FUNCTION
  1620.     In order to make room for the level text displayed by a
  1621.     SLIDER_KIND object one needs to know how much space the
  1622.     longest level string will occupy. Otherwise, the level
  1623.     text may overwrite the gadget label text or the slider
  1624.     container. This routine will rattle through all possible
  1625.     slider settings (as given via the Min and the Max
  1626.     level values) and determine the longest label string
  1627.     according to the font used.
  1628.  
  1629.    INPUTS
  1630.     Handle - Pointer to a LayoutHandle structure, as returned by
  1631.         a call to LT_CreateHandleTags().
  1632.  
  1633.     FormatString - The sprintf() style formatting string to be used
  1634.         to format the slider level settings into text.
  1635.         This is the same string you would pass in via
  1636.         the GTSL_LevelFormat tag when creating the
  1637.         slider object.
  1638.         Default: "%lD" for systems which have locale.library
  1639.             installed, "%ld" otherwise.
  1640.  
  1641.     DispFunc - A pointer to the function to filter the slider level
  1642.         values. The result of this function will then be
  1643.         used to format a string into the slider level text.
  1644.         This is the same parameter you would pass in via
  1645.         the GTSL_DispFunc tag when creating the slider
  1646.         object.
  1647.  
  1648.             NOTE: the routine will be called with a NULL Gadget
  1649.                 parameter, make sure your code will handle
  1650.                 this nicely.
  1651.  
  1652.         Default: no display function
  1653.  
  1654.     Min - The smallest value the slider can be set to. This is
  1655.         same value you would pass in via GTSL_Min when creating
  1656.         the slider object.
  1657.  
  1658.     Max - The largest value the slider can be set to. This is
  1659.         same value you would pass in via GTSL_Max when creating
  1660.         the slider object.
  1661.  
  1662.     MaxWidth - Pointer to a place to store the width of the
  1663.         longest level string in pixels. If you pass
  1664.         in NULL instead of the address of a variable
  1665.         no harm will be done.
  1666.  
  1667.     MaxLen - Pointer to a place to store the length of the
  1668.         longest level string in characters. If you pass
  1669.         in NULL instead of the address of a variable
  1670.         no harm will be done.
  1671.  
  1672.     FullCheck - TRUE will cause the code to rattle through all
  1673.         possible slider settings, starting from the
  1674.         minimum value, ending at the maximum value.
  1675.         While this may be a good idea for a display
  1676.         function to map slider levels to text strings
  1677.         of varying length it might be a problem when
  1678.         it comes to display a range of numbers from
  1679.         1 to 40,000: the code will loop through
  1680.         40,000 iterations trying to find the longest
  1681.         string.
  1682.  
  1683.         FALSE will cause the code to calculate the
  1684.         longest level string based only on the
  1685.         minimum and the maximum value to check.
  1686.         While this is certainly a good a idea when
  1687.         it comes to display a range of numbers from
  1688.         1 to 40,000 as only two values will be
  1689.         checked the code may fail to produce
  1690.         accurate results for sliders using display
  1691.         functions mapping slider levels to strings.
  1692.  
  1693.    RESULT
  1694.     Index - The slider level which gives the longest
  1695.         level string.
  1696.  
  1697.    NOTES
  1698.     Some compilers have trouble passing parameters in A5. In such
  1699.     a case it is recommended to use gtlayout.library/LT_NewLevelWidth
  1700.     instead.
  1701.  
  1702.    SEE ALSO
  1703.     gtlayout.library/LT_NewLevelWidth
  1704.  
  1705. gtlayout.library/LT_LockWindow                 gtlayout.library/LT_LockWindow
  1706.  
  1707.    NAME
  1708.     LT_LockWindow -- Block user access to a window.
  1709.  
  1710.    SYNOPSIS
  1711.     LT_LockWindow(Window);
  1712.                     A0
  1713.  
  1714.     VOID LT_LockWindow(struct Window *);
  1715.  
  1716.    FUNCTION
  1717.     The window will get a wait mouse pointer attached and a blank
  1718.     Requester, preventing any user gadgets from getting used. The
  1719.     window minimum and maximum sizes are set to the current window
  1720.     size so the user will be unable to resize the window or click
  1721.     on the zoom gadget.
  1722.  
  1723.     This routine nests, multiple calls to LT_LockWindow() using the
  1724.     same window will increment a usage counter, so exactly the
  1725.     same number of calls to LT_UnlockWindow() will be required to
  1726.     unlock the window.
  1727.  
  1728.    INPUTS
  1729.     Window - Pointer to window structure; passign NULL is harmless.
  1730.  
  1731.    RESULT
  1732.     none
  1733.  
  1734.    NOTES
  1735.     Do not close the window you have locked unless all the
  1736.     outstanding locks are freed or memory will be lost which
  1737.     can never be reclaimed. Before you close the window,
  1738.     call gtlayout.library/LT_DeleteWindowLock.
  1739.  
  1740.    SEE ALSO
  1741.     gtlayout.library/LT_DeleteWindowLock
  1742.  
  1743. gtlayout.library/LT_MenuControlTagList gtlayout.library/LT_MenuControlTagList
  1744.  
  1745.    NAME
  1746.     LT_MenuControlTagList -- Manipulate menus, menu/submenu items (V11)
  1747.  
  1748.    SYNOPSIS
  1749.     LT_MenuControlTagList(Window,Menu,Tags)
  1750.                            A0   A1     A2
  1751.  
  1752.     VOID LT_MenuControlTagList(struct Window *,struct Menu *,struct TagItem *);
  1753.  
  1754.     VOID LT_MenuControlTags(struct Window *,struct Menu *,...);
  1755.  
  1756.    FUNCTION
  1757.     This routine provides a rather efficient way to set and to clear,
  1758.     to enable and to disable a number of menus, menu/submenu items
  1759.     all at once.
  1760.  
  1761.     In v18 this routine was modified to disconnect a menu strip
  1762.     from a window if it is about to change checkmark states. In
  1763.     earlier releases or if a single menu is attached to several
  1764.     windows it is recommended that you disconnect the menu from
  1765.     the windows it is attached to before you call this routine.
  1766.  
  1767.     As of v18 this routine is smart enough to handle menu
  1768.     mutual exclusion.
  1769.  
  1770.    INPUTS
  1771.     Window - Pointer to Window this menu is attached to. Starting with
  1772.              gtlayout.library v16 this parameter may be NULL.
  1773.  
  1774.     Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
  1775.  
  1776.     Tags - Pointer to a list of tagitem values, as found
  1777.            in gtlayout.h
  1778.  
  1779.  
  1780.     Tags:
  1781.  
  1782.     LAMN_ID (ULONG) - Unique ID of menu/menu item/submenu item to
  1783.         manipulate.
  1784.  
  1785.     LAMN_Checked (BOOL) - Set the checkmark state of the
  1786.         menu/submenu item.
  1787.  
  1788.     LAMN_Disabled (BOOL) - Set the availability state of the
  1789.         menu/menu item/submenu item.
  1790.  
  1791.     LAMN_FullMenuNum (UWORD) - Intuition menu number of
  1792.         menu/submenu item to manipulate. You would pass the
  1793.         result of the FULLMENUNUM() macro here for the
  1794.         item in question. (V30)
  1795.  
  1796.    RESULT
  1797.     none
  1798.  
  1799.    EXAMPLE
  1800.     The following tagitem list will clear the checkmark and
  1801.     disable the menu item associated with ID 5 and set the
  1802.     checkmark for the item associated with ID 6:
  1803.  
  1804.         LAMN_ID,         5,
  1805.           LAMN_Checked,  FALSE,
  1806.           LAMN_Disabled, TRUE,
  1807.         LAMN_ID,         6,
  1808.           LAMN_Checked,  TRUE,
  1809.         TAG_DONE
  1810.  
  1811.    BUGS
  1812.     In library versions up to and including v17.2 this routine
  1813.     is broken. It won't do any harm, it just doesn't do what you
  1814.     want it to do.
  1815.  
  1816.     Up to and including V42.1 the library could fail to find the
  1817.     correct menu items corresponding to the LAMN_ID given. This
  1818.     has been fixed in V43.1.
  1819.  
  1820.     Up to and including V43.1 trying to change the attributes
  1821.     of an item with LAMN_ID whose ID number could not be found
  1822.     could lead to a crash. This has been fixed in V43.2.
  1823.  
  1824.    SEE ALSO
  1825.     gtlayout.library/LT_NewMenuTagList
  1826.  
  1827. gtlayout.library/LT_NewA                             gtlayout.library/LT_NewA
  1828.  
  1829.    NAME
  1830.     LT_NewA -- Add a new object to the user interface tree.
  1831.  
  1832.    SYNOPSIS
  1833.     LT_NewA(Handle,Tags);
  1834.              A0    A1
  1835.  
  1836.     VOID LT_NewA(LayoutHandle *,struct TagItem *);
  1837.  
  1838.     LT_New(Handle,...);
  1839.  
  1840.     VOID LT_New(LayoutHandle *,...);
  1841.  
  1842.    FUNCTION
  1843.     LT_NewA() is the routine you use to build the user interface,
  1844.     you give layout directions, design groups, etc. and finally
  1845.     call LT_BuildA() to turn these specifications into a window.
  1846.  
  1847.    INPUTS
  1848.     Handle - Pointer to LayoutHandle structure.
  1849.  
  1850.  
  1851.     This routine will accept almost all create-time tag items
  1852.     gadtools.library/CreateGadget will handle. In addition to
  1853.     this there are a bunch of extra gadget objects and extra
  1854.     tag items supported:
  1855.  
  1856.     All object types:
  1857.  
  1858.         LA_Type (LONG) - Type of the object to create, must be
  1859.             one of the following:
  1860.  
  1861.                 TEXT_KIND
  1862.                 VERTICAL_KIND
  1863.                 HORIZONTAL_KIND
  1864.                 END_KIND
  1865.                 FRAME_KIND
  1866.                 BOX_KIND
  1867.                 SLIDER_KIND
  1868.                 LISTVIEW_KIND
  1869.                 INTEGER_KIND
  1870.                 STRING_KIND
  1871.                 PASSWORD_KIND
  1872.                 PALETTE_KIND
  1873.                 BUTTON_KIND
  1874.                 CHECKBOX_KIND
  1875.                 NUMBER_KIND
  1876.                 GAUGE_KIND
  1877.                 CYCLE_KIND
  1878.                 POPUP_KIND
  1879.                 TAB_KIND
  1880.                 MX_KIND
  1881.                 XBAR_KIND
  1882.                 YBAR_KIND
  1883.                 TAPEDECK_KIND
  1884.                 LEVEL_KIND
  1885.                 BOOPSI_KIND
  1886.                 BLANK_KIND (V36)
  1887.                 FRACTION_KIND (V38)
  1888.                 IMAGE_KIND (V41)
  1889.  
  1890.         LA_LabelText (STRPTR) - The object label text to use.
  1891.  
  1892.         LA_LabelID (LONG) - The locale text ID of the string to
  1893.             use as the object label text.
  1894.  
  1895.                 NOTE: LT_NewA() will fail if you forget
  1896.                     to select a hook with LAHN_LocaleHook
  1897.                     at LT_CreateHandleTagList.
  1898.  
  1899.         LA_ID (LONG) - The gadget ID to use for this object.
  1900.  
  1901.                 NOTE: User ID values *MUST* be greater than 0,
  1902.                       negative values are reserved for internal
  1903.                       use.
  1904.  
  1905.         LA_Chars (LONG) - The width of this object measured in
  1906.             characters. If each character of the user interface
  1907.             font is 8 pixels wide an object with LA_Chars set to
  1908.             10 will usually be 80 pixels wide.
  1909.  
  1910.         LA_LabelChars (LONG) - This forces the internal gadget
  1911.             label width the layout engine calculates during the
  1912.             layout pass to a specific value. Note: this does
  1913.             not work well with all objects. (V9)
  1914.  
  1915.         LA_LabelPlace (LONG) - Where to place the gadget label.
  1916.             Not all objects will support all label positions:
  1917.  
  1918.                 PLACE_LEFT - Place label text left of object
  1919.                 PLACE_RIGHT - Place label text right of object
  1920.                 PLACE_ABOVE - Place label text above object
  1921.                 PLACE_IN - Place label text in object
  1922.                 PLACE_BELOW - Place label text below object
  1923.  
  1924.         LA_ExtraSpace (BOOL) - Add extra vertical/horizontal
  1925.             space before this object.
  1926.             Default: FALSE
  1927.  
  1928.         LA_ExtraFat (BOOL) - Make this object a bit larger
  1929.             than its usual size.
  1930.             Default: FALSE
  1931.  
  1932.         LA_NoKey (BOOL) - Don't let the user interface choose
  1933.             a keyboard shortcut for this object.
  1934.             Default: FALSE
  1935.  
  1936.         LA_HighLabel (BOOL) - Use highlight pen when rendering
  1937.             the gadget label text.
  1938.             Default: FALSE
  1939.  
  1940.         LA_BYTE (BYTE *) - Pointer to the variable that holds
  1941.             the "current value" of the object. The layout engine
  1942.             will retrieve this value initially during the creation
  1943.             of the object and maintain it during its lifespan.
  1944.             This means you do not need to worry about checking
  1945.             the state of the object, the user interface layout
  1946.             engine will do it for you.
  1947.  
  1948.         LA_UBYTE (UBYTE *) - Pointer to the variable that holds
  1949.             the "current value" of the object. The layout engine
  1950.             will retrieve this value initially during the creation
  1951.             of the object and maintain it during its lifespan.
  1952.             This means you do not need to worry about checking
  1953.             the state of the object, the user interface layout
  1954.             engine will do it for you.
  1955.  
  1956.         LA_WORD (WORD *) - Pointer to the variable that holds
  1957.             the "current value" of the object. The layout engine
  1958.             will retrieve this value initially during the creation
  1959.             of the object and maintain it during its lifespan.
  1960.             This means you do not need to worry about checking
  1961.             the state of the object, the user interface layout
  1962.             engine will do it for you.
  1963.  
  1964.         LA_UWORD (UWORD *) - Pointer to the variable that holds
  1965.             the "current value" of the object. The layout engine
  1966.             will retrieve this value initially during the creation
  1967.             of the object and maintain it during its lifespan.
  1968.             This means you do not need to worry about checking
  1969.             the state of the object, the user interface layout
  1970.             engine will do it for you.
  1971.  
  1972.         LA_BOOL (BOOL *) - Pointer to the variable that holds
  1973.             the "current value" of the object. The layout engine
  1974.             will retrieve this value initially during the creation
  1975.             of the object and maintain it during its lifespan.
  1976.             This means you do not need to worry about checking
  1977.             the state of the object, the user interface layout
  1978.             engine will do it for you.
  1979.  
  1980.         LA_LONG (LONG *) - Pointer to the variable that holds
  1981.             the "current value" of the object. The layout engine
  1982.             will retrieve this value initially during the creation
  1983.             of the object and maintain it during its lifespan.
  1984.             This means you do not need to worry about checking
  1985.             the state of the object, the user interface layout
  1986.             engine will do it for you.
  1987.  
  1988.         LA_ULONG (ULONG *) - Pointer to the variable that holds
  1989.             the "current value" of the object. The layout engine
  1990.             will retrieve this value initially during the creation
  1991.             of the object and maintain it during its lifespan.
  1992.             This means you do not need to worry about checking
  1993.             the state of the object, the user interface layout
  1994.             engine will do it for you.
  1995.  
  1996.         LA_STRPTR (STRPTR) - Pointer to the variable that holds
  1997.             the "current value" of the object. The layout engine
  1998.             will retrieve this value initially during the creation
  1999.             of the object and maintain it during its lifespan.
  2000.             This means you do not need to worry about checking
  2001.             the state of the object, the user interface layout
  2002.             engine will do it for you.
  2003.  
  2004.         LA_FRACTION (FRACTION *) - Pointer to the variable that holds
  2005.             the "current value" of the object. The layout engine
  2006.             will retrieve this value initially during the creation
  2007.             of the object and maintain it during its lifespan.
  2008.             This means you do not need to worry about checking
  2009.             the state of the object, the user interface layout
  2010.             engine will do it for you.
  2011.  
  2012.  
  2013.         BLANK_KIND (transparent placeholder):
  2014.  
  2015.             (requires gtlayout.library V36 or higher)
  2016.  
  2017.             No tags are defined for this type of object.
  2018.  
  2019.  
  2020.         BOOPSI_KIND:
  2021.  
  2022.             (requires gtlayout.library V10 or higher)
  2023.  
  2024.             LABO_TagCurrent (Tag) - The Tag ID that represents the
  2025.                 current object value. For PROPGCLASS this would be
  2026.                 PGA_Top.
  2027.  
  2028.             LABO_TagTextAttr (Tag) - The Tag ID that represents the
  2029.                 TextAttr value the object expects. For gadgets this
  2030.                 would be GA_TextAttr.
  2031.  
  2032.             LABO_TagDrawInfo (Tag) - The Tag ID that represents the
  2033.                 DrawInfo value the object expects.
  2034.  
  2035.             LABO_TagLink (Tag) - The Tag ID that represents a pointer
  2036.                 to a different object the object expects. For the
  2037.                 colorwheel.gadget this would be WHEEL_GradientSlider.
  2038.  
  2039.             LABO_TagScreen (Tag) - The Tag ID that represents the
  2040.                 screen the object expects. For the colorwheel.gadget
  2041.                 this would be WHEEL_Screen.
  2042.  
  2043.             LABO_Link (LONG) - The ID of the object this object should
  2044.                 be linked to. This will be resolved later when gadgets
  2045.                 are created.
  2046.  
  2047.                     NOTE: Forward references are not resolved, only
  2048.                         backward references are allowed. This means that
  2049.                         if you wish to link object A to object B,
  2050.                         object A must be created before object B
  2051.                         is created.
  2052.  
  2053.             LABO_ClassInstance (Class *) - This is the first parameter
  2054.                 you would pass to NewObjectA().
  2055.  
  2056.                     NOTE: Only classes derived from gadgetclass and
  2057.                       gadgetclass itself may be used.
  2058.  
  2059.             LABO_ClassName (STRPTR) - This is the second parameter you would
  2060.                 pass to NewObject().
  2061.  
  2062.                     NOTE: Only classes derived from gadgetclass and
  2063.                         gadgetclass itself may be used.
  2064.  
  2065.             LABO_ClassLibraryName (STRPTR) - This tag is particularly useful
  2066.                 for gadget class implementations wrapped into libraries, such as
  2067.                 colorwheel.gadget. When opened, they make the classes they
  2068.                 represent publicly available so subsequent calls to
  2069.                 NewObject(NULL,<Classname>,...) can be made. The
  2070.                 LABO_ClassLibraryName tag will cause gtlayout.library to open
  2071.                 the class library before any calls to NewObject() are made.
  2072.  
  2073.                     NOTE: Only classes derived from gadgetclass and
  2074.                         gadgetclass itself may be used.
  2075.  
  2076.                         The LABO_ClassLibraryName tag requires that you
  2077.                         specify the class name with the LABO_ClassName. It is
  2078.                         not enough to just use the LABO_ClassLibraryName tag.
  2079.  
  2080.             LABO_ExactWidth (WORD) - This is the exact width of the object to
  2081.                 use. This effectively overrides whatever you specified using
  2082.                 the LA_Chars tag and keeps gtlayout.library from shrinking and
  2083.                 expanding the object as needed.
  2084.  
  2085.             LABO_ExactHeight (WORD) - This is the exact height of the object to
  2086.                 use. This effectively overrides whatever you specified using
  2087.                 the LA_Lines tag and keeps gtlayout.library from shrinking and
  2088.                 expanding the object as needed.
  2089.  
  2090.             LABO_RelFontHeight (WORD) - This tag affects the height of the
  2091.                 object; when specified, it is derived from the user interface
  2092.                 font height plus the value given with LABO_RelFontHeight.
  2093.  
  2094.             LABO_FullWidth (BOOL) - Use this tag if you wish the object to
  2095.                 cover the entire width of the group it resides within.
  2096.  
  2097.             LABO_FullHeight (BOOL) - Use this tag if you wish the object to
  2098.                 cover the entire height of the group it resides within.
  2099.  
  2100.             LABO_ActivateHook (struct Hook *) - Hook to invoke when the
  2101.                 layout engine decides that this particular object should
  2102.                 be activated. The hook is called with the following
  2103.                 parameters:
  2104.  
  2105.                 Success = ActivateFunc(struct Hook *Hook,LayoutHandle *Handle,
  2106.                   D0                                 A0                  A2
  2107.  
  2108.                              Object *object)
  2109.                                        A1
  2110.  
  2111.                 The object pointer actually refers to the instance of the
  2112.                 BOOPSI object created. Return FALSE if your object could not
  2113.                 be activated, TRUE if it worked. If you return TRUE, no special
  2114.                 keyboard event will be generated. (V13)
  2115.  
  2116.             NOTE: All tags passed to LT_New() for BOOPSI_KIND objects are
  2117.                 passed through to NewObjectA() later. The library makes
  2118.                 a copy of the tag item list, so all data valid in the
  2119.                 scope when LT_New() is called must also be valid later
  2120.                 when LT_Build() is invoked.
  2121.  
  2122.                 The gadget label is *NOT* passed through to the object,
  2123.                 it effectively receives the label a plain gadtools object
  2124.                 would receive, similar to what happens to FRAME_KIND
  2125.                 objects and the like.
  2126.  
  2127.  
  2128.         BOX_KIND (multiline text display):
  2129.  
  2130.             LABX_Chars (LONG) - The width of this object in
  2131.                 characters. The layout routine will try to make
  2132.                 sure that the given number of characters will
  2133.                 fit into a single line of text in this box.
  2134.                 This may be a problem with proportional spaced
  2135.                 fonts.
  2136.                Default: 10
  2137.  
  2138.             LABX_Labels (STRPTR *) - The label texts to display
  2139.                 on the right hand side of the box. Terminate
  2140.                 this array with NULL.
  2141.  
  2142.             LABX_Lines (STRPTR *) - The text to display in the
  2143.                 box. Terminate this array with NULL.
  2144.  
  2145.             LABX_Rows (LONG) - The height of this object in
  2146.                 characters.
  2147.  
  2148.             LABX_AlignText (LONG) - Controls how text is aligned
  2149.                 in box lines:
  2150.  
  2151.                     ALIGNTEXT_LEFT - Align text to the left edge
  2152.                     ALIGNTEXT_CENTERED - Centre the text
  2153.                     ALIGNTEXT_RIGHT - Align text to the right edge
  2154.                     ALIGNTEXT_PAD - Pad text lines
  2155.  
  2156.                 Default: ALIGNTEXT_LEFT
  2157.  
  2158.             LABX_DrawBox (BOOL) - Draw a recessed bevel box
  2159.                 around the text box.
  2160.                 Default: FALSE
  2161.  
  2162.             LABX_FirstLabel (LONG) - Locale string ID of the first
  2163.                 text to use as a box label. Works in conjunction
  2164.                 with LABX_LastLabel.
  2165.  
  2166.             LABX_LastLabel (LONG) - Locale string ID of the last
  2167.                 text to use as a box label. Works in conjunction
  2168.                 with LABX_FirstLabel. When building the interface the
  2169.                 code will loop from FirstLabel..LastLabel, look
  2170.                 up the corresponding locale strings and use the
  2171.                 data to make up the label text to appear at the
  2172.                 right hand side of the box.
  2173.  
  2174.             LABX_LabelTable (LONG *) - Pointer to an array of IDs
  2175.                 to use for building the box labels. This requires
  2176.                 that a locale hook is provided with the layout handle.
  2177.                 The array is terminated by -1.
  2178.  
  2179.             LABX_ReserveSpace (BOOL) - Allocate extra memory to hold
  2180.                 the contents of the lines displayed. This avoids nasty
  2181.                 side-effects when refreshing this object.
  2182.                 Default: FALSE
  2183.  
  2184.             LABX_FirstLine (LONG) - Locale string ID of the first
  2185.                 text to print inside the box. Works in conjunction
  2186.                 with LABX_LastLine. (V26)
  2187.  
  2188.             LABX_LastLine (LONG) - Locale string ID of the last
  2189.                 text to print inside the box. Works in conjunction
  2190.                 with LABX_FirstLine. (V26)
  2191.  
  2192.             LABX_LineTable (LONG *) - Pointer to an array of IDs
  2193.                 to use for building the box contents lines. This requires
  2194.                 that a locale hook is provided with the layout handle.
  2195.                 The array is terminated by -1. (V28)
  2196.  
  2197.             LABX_Line (STRPTR) - Line to display in the box, may
  2198.                 contain '\n' line break characters, the layout engine
  2199.                 will chop the single line into single consecutive lines
  2200.                 following the '\n' chars. (V31)
  2201.  
  2202.             LABX_LineID (LONG) - Locale ID of line text to display in the
  2203.                 box, may contain '\n' line break characters, the layout
  2204.                 engine will chop the single line into single consecutive lines
  2205.                 following the '\n' chars. (V31)
  2206.  
  2207.             LABX_TextPen (WORD) - Box text colour to use. (V40)
  2208.  
  2209.             LABX_BackPen (WORD) - Box text background colour to use. (V40)
  2210.  
  2211.             LABX_Spacing (UWORD) - Request that additional pixels should
  2212.                 separate lines of text. (V41)
  2213.                 Default: 0
  2214.  
  2215.  
  2216.         BUTTON_KIND:
  2217.  
  2218.             LA_Label (STRPTR)
  2219.             LA_LabelID (LONG) - These two define the button label, i.e.
  2220.                 the text that is printed within the button box. Optionally,
  2221.                 this text may include newline characters ("\n") which will
  2222.                 cause the button text to be broken into several lines.
  2223.                 This particular feature requires gtlayout.library v12 or
  2224.                 higher. Single line label have always been supported.
  2225.  
  2226.             LABT_ReturnKey (BOOL) - Let the user operate this
  2227.                 button by pressing the return key, making it the
  2228.                 so-called default button, or default choice. The
  2229.                 button select box will appear slightly bolder than
  2230.                 normal buttons are.
  2231.  
  2232.                     NOTE: there can be only one single button per
  2233.                         window to sport this feature.
  2234.  
  2235.                 Default: FALSE
  2236.  
  2237.             LABT_EscKey (BOOL) - Let the user operate this
  2238.                 button by pressing the Escape key.
  2239.  
  2240.                     NOTE: there can be only one single button per
  2241.                         window to use this feature.
  2242.  
  2243.                 Default: FALSE
  2244.  
  2245.             LABT_ExtraFat (BOOL) - Make this button a bit
  2246.                 larger than usual.
  2247.                 Default: FALSE
  2248.  
  2249.             LABT_Lines (STRPTR *) - Use the given string array
  2250.                 to create a multiline gadget label. Terminate the
  2251.                 array with a NULL. (V12)
  2252.  
  2253.             LABT_FirstLine (LONG) - Locale ID of first label line. (V12)
  2254.  
  2255.             LABT_LastLine (LONG) - Locale ID of last label line. (V12)
  2256.  
  2257.             LABT_DefaultCorrection (BOOL) - Make the button slightly
  2258.                 wider and taller so its size matches the default
  2259.                 button. (V21)
  2260.  
  2261.             LABT_Smaller (BOOL) - Make this button a little smaller
  2262.                 than usual. (V21)
  2263.  
  2264.  
  2265.         CYCLE_KIND:
  2266.  
  2267.             LACY_FirstLabel (LONG) - Locale string ID of the first
  2268.                 text to use as a label. Works in conjunction
  2269.                 with LACY_LastLabel.
  2270.  
  2271.             LACY_LastLabel (LONG) - Locale string ID of the last
  2272.                 text to use as a label. Works in conjunction
  2273.                 with LACY_FirstLabel. When building the interface the
  2274.                 code will loop from FirstLabel..LastLabel, look
  2275.                 up the corresponding locale strings and use the
  2276.                 data to make up the label text.
  2277.  
  2278.             LACY_LabelTable (LONG *) - Pointer to an array of IDs
  2279.                 to use for building the cycle labels. This requires
  2280.                 that a locale hook is provided with the layout handle.
  2281.                 The array is terminated by -1.
  2282.  
  2283.             LACY_TabKey (BOOL) - Connect this object to the tabulator
  2284.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2285.                 to cycle to the previous entry. (V9)
  2286.  
  2287.                     NOTE: there can be only one single button per
  2288.                         window to use this feature.
  2289.  
  2290.                 Default: FALSE
  2291.  
  2292.             LACY_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2293.                 which will be set to the gadget's current setting.
  2294.                 If this tag is set, you will hear no events from this
  2295.                 object any more. (V7)
  2296.  
  2297.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2298.                         which may be generated if the layout
  2299.                         engine runs out of memory when rebuilding
  2300.                         the user interface.
  2301.  
  2302.  
  2303.         FRACTION_KIND:
  2304.  
  2305.             (requires gtlayout.library V38 or higher)
  2306.  
  2307.             This is a special kind of STRING_KIND which comes with a
  2308.             special input filter. It will allow only for floating point
  2309.             numbers to be entered, i.e. numbers (`0'-`9') and one
  2310.             decimal point (`.' or whatever your current locale uses
  2311.             as the decimal point character). What you will receive as
  2312.             user input text will be in the following format:
  2313.  
  2314.                 (0|#[0-9]).(0|#[0-9])
  2315.  
  2316.             Or in other words, text like this will be returned:
  2317.  
  2318.                 0.0
  2319.                 7.0
  2320.                 0.9
  2321.                 146654.0
  2322.  
  2323.             NOTE: While this object type did exist in earlier library
  2324.                   versions support for it was removed in V33. It was
  2325.                   eventually reintroduced with the functionality described
  2326.                   above in V38.
  2327.  
  2328.             LAFR_IncrementerHook (struct Hook *) - Hook to invoke when the
  2329.                 incrementer arrows are used. The hook function will receive
  2330.                 three parameters and has to return a result code:
  2331.  
  2332.                     a0 - (struct Hook *)  Pointer to this hook
  2333.                     a2 - (STRPTR) Current value of this object
  2334.                     a1 - (LONG) Either INCREMENTERMSG_Decrement or
  2335.                                 INCREMENTERMSG_Increment
  2336.  
  2337.                 If the hook function modifies the current value it must
  2338.                 return TRUE, otherwise FALSE must be returned. If you return
  2339.                 TRUE, then the library will update the object. (V40)
  2340.  
  2341.             This object type accepts all the GTST_#? tag items.
  2342.  
  2343.  
  2344.         FRAME_KIND (fixed size general purpose display,
  2345.             you may render into it):
  2346.  
  2347.             LAFR_InnerWidth (LONG) - Inner width of the
  2348.                 display box.
  2349.  
  2350.             LAFR_InnerHeight (LONG) - Inner height of the
  2351.                 display box.
  2352.  
  2353.             LAFR_DrawBox (BOOL) - Draw a recessed bevel box
  2354.                 around the display box.
  2355.                 Default: FALSE
  2356.  
  2357.             LAFR_RefreshHook (struct Hook *) - Hook to call
  2358.                 when refreshing/redrawing this object. See
  2359.                 gtlayout.h for more information. (V9)
  2360.  
  2361.             LAFR_GenerateEvents (BOOL) - If TRUE, clicking
  2362.                 inside the FRAME_KIND object will generate
  2363.                 IDCMP_GADGETUP/IDCMP_GADGETDOWN events. If
  2364.                 you wish to know where the click occured,
  2365.                 make a copy of the Window->MouseX/Y entries
  2366.                 before you call LT_HandleInput()/LT_GetIMsg(). (V28)
  2367.                 Default: FALSE
  2368.  
  2369.  
  2370.         GAUGE_KIND (general purpose progress report display):
  2371.  
  2372.             LAGA_Percent (LONG) - Indicator position, can range
  2373.                 from 0..100.
  2374.                 Default: 0
  2375.  
  2376.             LAGA_InfoLength (LONG) - Maximum number of characters
  2377.                 to reserve for text printed in the gauge display.
  2378.                 Default: 0
  2379.  
  2380.             LAGA_InfoText (STRPTR) - Text to print in the gauge
  2381.                 display.
  2382.  
  2383.             LAGA_Tenth (BOOL) - Instead of a continuously growing
  2384.                 bar you will get a set of exactly ten blocks,
  2385.                 each separated by a hairline. (V19)
  2386.                 Default: FALSE
  2387.  
  2388.                LAGA_NoTicks (BOOL) - If TRUE suppresses drawing the
  2389.                    ticks below the gauge box.
  2390.                    Default: FALSE
  2391.  
  2392.  
  2393.         IMAGE_KIND (display area for Image or BitMap data):
  2394.  
  2395.             (requires gtlayout.library V41 or higher)
  2396.  
  2397.             LAIM_Image (struct Image *) - Image to draw in this
  2398.                 place. When the user interface is built, it will
  2399.                 be drawn using intuition.library/DrawImage().
  2400.  
  2401.             LAIM_BitMap (struct BitMap *) - You can supply a
  2402.                 BitMap instead of an Image which will be drawn
  2403.                 using either graphics.library/BltBitMapRastPort()
  2404.                 or graphics.library/BltMaskBitMapRastPort() if
  2405.                 a mask is provided.
  2406.  
  2407.             LAIM_BitMapLeft (UWORD) - Left corner of the image data
  2408.                 to blit into the window (the second parameter for
  2409.                 BltBitMapRastPort()).
  2410.  
  2411.             LAIM_BitMapTop (UWORD) - Top corner of the image data
  2412.                 to blit into the window (the third parameter for
  2413.                 BltBitMapRastPort()).
  2414.  
  2415.             LAIM_BitMapWidth (UWORD) - Width of the bitmap area to
  2416.                 blit into the window.
  2417.  
  2418.             LAIM_BitMapHeight (UWORD) - Height of the bitmap area to
  2419.                 blit into the window.
  2420.  
  2421.             LAIM_BitMapMask (PLANEPTR) - Pointer to a bit plane mask
  2422.                 to blit the image bitmap through. Must follow the
  2423.                 rules documented for for BltMaskBitMapRastPort().
  2424.                 The blit operation will use the minterm for
  2425.                 transparency.
  2426.  
  2427.  
  2428.         INTEGER_KIND:
  2429.  
  2430.             LAIN_LastGadget (BOOL) - Pressing return with this
  2431.                 gadget active will stop activating the next
  2432.                 following string gadget type if TRUE is passed.
  2433.                 Default: FALSE
  2434.  
  2435.             LAIN_Min (LONG) - Minimum accepted numeric value.
  2436.                 Default: -2147483647
  2437.  
  2438.             LAIN_Max (LONG) - Maximum accepted numeric value.
  2439.                 Default:  2147483647
  2440.  
  2441.             LAIN_UseIncrementers (BOOL) - Use TRUE to add incrementer
  2442.                 arrow buttons to the right of the numeric entry field.
  2443.                 These buttons will let you cycle through a set of
  2444.                 numbers to be displayed in the numeric entry field.
  2445.                 Default: FALSE
  2446.  
  2447.             LAIN_HistoryLines (LONG) - Number of numbers entered to
  2448.                 keep as a backlog.
  2449.                 Default: 0
  2450.  
  2451.             LAIN_HistoryHook (struct Hook *) - Hook code to call when
  2452.                 entering a number into the backlog. See gtlayout.h for
  2453.                 more information.
  2454.                 Default: NULL
  2455.  
  2456.             LAIN_IncrementerHook (struct Hook *) - Hook code to call
  2457.                 when cycling through numeric values. See gtlayout.h for
  2458.                 more information.
  2459.                 Default: NULL
  2460.  
  2461.             LAIN_Activate (BOOL) - When the window opens, make this
  2462.                 gadget the active one. (V21)
  2463.  
  2464.                     NOTE: There can be only one gadget of this type
  2465.                         per window.
  2466.  
  2467.                 Default: FALSE
  2468.  
  2469.  
  2470.         LEVEL_KIND:
  2471.  
  2472.             All tags are supported which SLIDER_KIND supports.
  2473.             The gadget level display however, can only be aligned
  2474.             to the left border.
  2475.  
  2476.             LAVL_Freedom (WORD) - Selects the orientation of the
  2477.                 slider body; can be either FREEHORIZ or FREEVERT. (V41)
  2478.  
  2479.                 Default: FREEHORIZ
  2480.  
  2481.             LAVL_Ticks (WORD) - Selects if and where to place tick
  2482.                 marks next to the slider body. Can be one of the
  2483.                 the following: TICKS_None (no ticks), TICKS_Left
  2484.                 (place ticks left of the body), TICKS_Above (place
  2485.                 ticks above the body), TICKS_Both (place ticks on
  2486.                 both sides of the body). (V41)
  2487.  
  2488.                 Default: TICKS_None
  2489.  
  2490.             LAVL_NumTicks (LONG) - Number of tick marks to draw. (V41)
  2491.  
  2492.             LAVL_Lines (LONG) - Height of the slider, if FREEVERT. (V41)
  2493.  
  2494.  
  2495.         LISTVIEW_KIND:
  2496.  
  2497.             LALV_ExtraLabels (STRPTR *) - Place extra line
  2498.                 labels at the right of the box. Terminate
  2499.                 this array with NULL.
  2500.  
  2501.             LALV_Labels (STRPTR *) - The labels to display
  2502.                 inside the box, you can pass this array of
  2503.                 strings in rather than passing an initialized
  2504.                 List of text via GTLV_Labels. Terminate
  2505.                 this array with NULL.
  2506.  
  2507.             LALV_CursorKey (BOOL) - Let the user operate this
  2508.                 listview using the cursor keys.
  2509.  
  2510.                     NOTE: there can be only one single listview
  2511.                         per window to sport this feature.
  2512.  
  2513.                 Default: FALSE
  2514.  
  2515.             LALV_Lines (LONG) - The number of text lines this
  2516.                 listview is to display.
  2517.  
  2518.             LALV_Link (LONG) - The Gadget ID of a string gadget
  2519.                 to attach to this listview.
  2520.  
  2521.                     NOTE: you need to
  2522.                         add the Gadget in question before you add the
  2523.                         listview to refer to it or the layout routine
  2524.                         will get confused.
  2525.  
  2526.                 Passing the value NIL_LINK will create a listview
  2527.                 which displays the currently selected item, otherwise
  2528.                 you will get a read-only list.
  2529.  
  2530.             LALV_FirstLabel (LONG) - Locale string ID of the first
  2531.                 text to use as a list label. Works in conjunction
  2532.                 with LALV_LastLabel.
  2533.  
  2534.             LALV_LastLabel (LONG) - Locale string ID of the last
  2535.                 text to use as a list label. Works in conjunction
  2536.                 with LALV_FirstLabel. When building the interface the
  2537.                 code will loop from FirstLabel..LastLabel, look
  2538.                 up the corresponding locale strings and use the
  2539.                 data to make up the label text to appear in the
  2540.                 list.
  2541.  
  2542.             LALV_LabelTable (LONG *) - Pointer to an array of IDs
  2543.                 to use for building the listview contents. This requires
  2544.                 that a locale hook is provided with the layout handle.
  2545.                 The array is terminated by -1.
  2546.  
  2547.             LALV_MaxGrowX (LONG) - Maximum width of this object
  2548.                 measured in characters. When the first layout pass
  2549.                 is finished and there is still enough space left
  2550.                 to make the listview wider, the width is increased
  2551.                 until it hits the limit specified using this tag.
  2552.  
  2553.                     NOTE: there can be only one single listview
  2554.                         per window to sport this feature.
  2555.  
  2556.                 Default: 0
  2557.  
  2558.             LALV_MaxGrowY (LONG) - Maximum height of this object
  2559.                 measured in lines. When the first layout pass is
  2560.                 finished and there is still enough space left to
  2561.                 make the listview higher, the height is increased
  2562.                 until it hits the limit specified using this tag.
  2563.  
  2564.                     NOTE: there can be only one single listview
  2565.                         per window to sport this feature.
  2566.  
  2567.                 Default: 0
  2568.  
  2569.             LALV_ResizeX (BOOL) - Makes this listview resizable
  2570.                 in the horizontal direction, attaches a sizing
  2571.                 gadget to the window to open and handles window
  2572.                 resize operations automatically. (V9)
  2573.  
  2574.                     NOTE: there can be only one single listview
  2575.                         per window to sport this feature.
  2576.  
  2577.                         Also listen to IDCMP_CLOSEWINDOW events
  2578.                         which may be generated if the layout
  2579.                         engine runs out of memory when rebuilding
  2580.                         the user interface.
  2581.  
  2582.                 Default: FALSE
  2583.  
  2584.             LALV_ResizeY (BOOL) - Makes this listview resizable
  2585.                 in the vertical direction, attaches a sizing
  2586.                 gadget to the window to open and handles window
  2587.                 resize operations automatically. (V9)
  2588.  
  2589.                     NOTE: there can be only one single listview
  2590.                         per window to sport this feature.
  2591.  
  2592.                         Also listen to IDCMP_CLOSEWINDOW events
  2593.                         which may be generated if the layout
  2594.                         engine runs out of memory when rebuilding
  2595.                         the user interface.
  2596.  
  2597.                 Default: FALSE
  2598.  
  2599.             LALV_MinChars (WORD) - Minimum width for this
  2600.                 object, measured in characters. Used in
  2601.                 conjunction with LALV_ResizeX. (V9)
  2602.  
  2603.             LALV_MinLines (WORD) - Minimum height for this
  2604.                 object, measured in lines. Used in
  2605.                 conjunction with LALV_ResizeY. (V9)
  2606.  
  2607.             LALV_LockSize (BOOL) - After doing the initial layout
  2608.                 for this object, do not adapt its size again during
  2609.                 subsequent layouts. This is particularly useful if
  2610.                 you have a LISTVIEW_KIND object in a paged group
  2611.                 and keep adding new entries to the list. You need
  2612.                 to specify an object width using LA_Chars, otherwise
  2613.                 the layout engine may make it not wide enough to
  2614.                 display any entries. (V8)
  2615.  
  2616.             LALV_FlushLabelLeft (BOOL) - For a gadget label placed
  2617.                 above the listview align the text to the left edge
  2618.                 of the view. (V9)
  2619.  
  2620.             LALV_TextAttr (struct TextAttr *) - You can specify a
  2621.                 fixed-width font to be used for the list display.
  2622.                 The TextAttr (or TTextAttr) you provide must be ready
  2623.                 to go so the layout code can open the font later.
  2624.  
  2625.                 To get the current system default font, which is
  2626.                 guaranteed to be fixed-width, pass ~0 instead of a
  2627.                 pointer to a TextAttr structure. (V10)
  2628.  
  2629.                     NOTE: The font *MUST* be fixed-width or the layout
  2630.                         will fail.
  2631.  
  2632.                          Choose your font in such a way that it matches
  2633.                          in width and height with the other probably
  2634.                          proportional-spaced user interface font.
  2635.  
  2636.                          If the layout engine decides to step down in
  2637.                          font size, all LISTVIEW_KIND objects which were
  2638.                          configured to use a special fixed-width font
  2639.                          will `forget' about it. This won't matter much
  2640.                          as the fonts the engine chooses will always be
  2641.                          fixed-width anyway.
  2642.  
  2643.             LALV_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2644.                 which will be set to the gadget's current setting.
  2645.                 If this tag is set, you will hear no events from this
  2646.                 object any more. (V23)
  2647.  
  2648.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2649.                         which may be generated if the layout
  2650.                         engine runs out of memory when rebuilding
  2651.                         the user interface.
  2652.  
  2653.             LALV_Selected (LONG) - In this context, this tag is an
  2654.                 alias for GTLV_Selected. See
  2655.                 gtlayout.library/LT_SetAttributes for more information
  2656.                 on how the meaning of this tag differs from this (V34).
  2657.  
  2658.  
  2659.         MX_KIND:
  2660.  
  2661.             LAMX_FirstLabel (LONG) - Locale string ID of the first
  2662.                 text to use as a label. Works in conjunction
  2663.                 with LAMX_LastLabel.
  2664.  
  2665.             LAMX_LastLabel (LONG) - Locale string ID of the last
  2666.                 text to use as a label. Works in conjunction
  2667.                 with LAMX_FirstLabel. When building the interface the
  2668.                 code will loop from FirstLabel..LastLabel, look
  2669.                 up the corresponding locale strings and use the
  2670.                 data to make up the label text.
  2671.  
  2672.             LAMX_LabelTable (LONG *) - Pointer to an array of IDs
  2673.                 to use for building the radio labels. This requires
  2674.                 that a locale hook is provided with the layout handle.
  2675.                 The array is terminated by -1.
  2676.  
  2677.             LAMX_TabKey (BOOL) - Connect this object to the tabulator
  2678.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2679.                 to cycle to the previous entry. (V9)
  2680.  
  2681.                     NOTE: there can be only one single button per
  2682.                         window to use this feature.
  2683.  
  2684.                 Default: FALSE
  2685.  
  2686.             LAMX_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2687.                 which will be set to the gadget's current setting.
  2688.                 If this tag is set, you will hear no events from this
  2689.                 object any more. (V7)
  2690.  
  2691.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2692.                         which may be generated if the layout
  2693.                         engine runs out of memory when rebuilding
  2694.                         the user interface.
  2695.  
  2696.  
  2697.         PALETTE_KIND:
  2698.  
  2699.             LAPA_SmallPalette (BOOL) - Make the palette display
  2700.                 a bit smaller than usual.
  2701.                 Default: FALSE
  2702.  
  2703.             LAPA_Lines (LONG) - Number of lines the palette
  2704.                 display should cover.
  2705.                 Default: No preference
  2706.  
  2707.             LAPA_UsePicker (BOOL) - This tag effectively changes the
  2708.                 gadget type. Instead of a list of colours to pick from
  2709.                 the user will see a rectangle filled in the selected
  2710.                 colour with a picker button next to it. This gadget
  2711.                 will generate IDCMP_IDCMPUPDATE events when the picker
  2712.                 button is pressed. (V10)
  2713.  
  2714.  
  2715.         PASSWORD_KIND (string gadget type which does not
  2716.             display its contents):
  2717.  
  2718.             LAPW_LastGadget (BOOL) - Pressing return with this
  2719.                 gadget active will stop activating the next
  2720.                 following string gadget type if TRUE is passed.
  2721.                 Default: FALSE
  2722.  
  2723.             LAPW_HistoryLines (LONG) - Number of lines to keep as
  2724.                 a backlog.
  2725.                 Default: 0
  2726.  
  2727.             LAPW_HistoryHook (struct Hook *) - Hook code to call
  2728.                 when entering a line into the backlog. See gtlayout.h
  2729.                 for more information.
  2730.                 Default: NULL
  2731.  
  2732.             LAPW_Activate (BOOL) - When the window opens, make this
  2733.                 gadget the active one. (V21)
  2734.  
  2735.                     NOTE: There can be only one gadget of this type
  2736.                         per window.
  2737.  
  2738.                 Default: FALSE
  2739.  
  2740.             This object type accepts all the GTST_#? tag items.
  2741.  
  2742.  
  2743.         POPUP_KIND:
  2744.  
  2745.             (This features requires gtlayout.library v22 or higher
  2746.              and Kickstart 3.0 or higher).
  2747.  
  2748.             LAPU_FirstLabel (LONG) - Locale string ID of the first
  2749.                 text to use as a label. Works in conjunction
  2750.                 with LAPU_LastLabel.
  2751.  
  2752.             LAPU_LastLabel (LONG) - Locale string ID of the last
  2753.                 text to use as a label. Works in conjunction
  2754.                 with LAPU_FirstLabel. When building the interface the
  2755.                 code will loop from FirstLabel..LastLabel, look
  2756.                 up the corresponding locale strings and use the
  2757.                 data to make up the label text.
  2758.  
  2759.             LAPU_LabelTable (LONG *) - Pointer to an array of IDs
  2760.                 to use for building the cycle labels. This requires
  2761.                 that a locale hook is provided with the layout handle.
  2762.                 The array is terminated by -1.
  2763.  
  2764.             LAPU_TabKey (BOOL) - Connect this object to the tabulator
  2765.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2766.                 to cycle to the previous entry.
  2767.  
  2768.                     NOTE: there can be only one single button per
  2769.                         window to use this feature.
  2770.  
  2771.                 Default: FALSE
  2772.  
  2773.             LAPU_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2774.                 which will be set to the gadget's current setting.
  2775.                 If this tag is set, you will hear no events from this
  2776.                 object any more.
  2777.  
  2778.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2779.                         which may be generated if the layout
  2780.                         engine runs out of memory when rebuilding
  2781.                         the user interface.
  2782.  
  2783.             LAPU_CentreActive (BOOL) - If TRUE, the popup menu will
  2784.                 appear with the currently active entry centred below
  2785.                 the mouse pointer. (V31)
  2786.  
  2787.             LAPU_Labels (STRPTR *) - Pointer to NULL-terminated array
  2788.                 of strings that are the choices offered.
  2789.  
  2790.  
  2791.         SCROLLER_KIND:
  2792.  
  2793.             LASC_Thin (BOOL) - Make the scroller a bit thinner
  2794.                 than usual.
  2795.                 Default: FALSE
  2796.  
  2797.             GA_RelVerify (BOOL) - Hear every IDCMP_GADGETUP
  2798.                 event from scroller.
  2799.                 Default: TRUE
  2800.  
  2801.                         NOTE: This is different from what
  2802.                          gadtools.library uses.
  2803.  
  2804.             GA_Immediate (BOOL) - Hear every IDCMP_GADGETDOWN
  2805.                 event from scroller
  2806.                 Default: TRUE
  2807.  
  2808.                         NOTE: This is different from what
  2809.                          gadtools.library uses.
  2810.  
  2811.  
  2812.         SLIDER_KIND:
  2813.  
  2814.             LASL_FullCheck: TRUE will cause the code to rattle
  2815.                 through all possible slider settings, starting
  2816.                 from the minimum value, ending at the maximum value.
  2817.                 While this may be a good idea for a display
  2818.                 function to map slider levels to text strings
  2819.                 of varying length it might be a problem when
  2820.                 it comes to display a range of numbers from
  2821.                 1 to 40,000: the code will loop through
  2822.                 40,000 iterations trying to find the longest
  2823.                 string.
  2824.  
  2825.                 FALSE will cause the code to calculate the
  2826.                 longest level string based only on the
  2827.                 minimum and the maximum value to check.
  2828.                 While this is certainly a good a idea when
  2829.                 it comes to display a range of numbers from
  2830.                 1 to 40,000 as only two values will be
  2831.                 checked the code may fail to produce
  2832.                 accurate results for sliders using display
  2833.                 functions mapping slider levels to strings.
  2834.  
  2835.                 Default: TRUE
  2836.  
  2837.  
  2838.         STRING_KIND:
  2839.  
  2840.             LAST_LastGadget (BOOL) - Pressing return with this
  2841.                 gadget active will stop activating the next
  2842.                 following string gadget type if TRUE is passed.
  2843.                 Default: FALSE
  2844.  
  2845.             LAST_Link (LONG) - Gadget ID of the listview to attach
  2846.                 this string gadget to.
  2847.  
  2848.                     NOTE: you need to add the string gadget before
  2849.                         you add the listview to refer to it or the
  2850.                         layout routine will get confused.
  2851.  
  2852.             LAST_Picker (BOOL) - Attach a `select' button to the
  2853.                 right hand side of the string gadget.
  2854.                 Default: FALSE
  2855.  
  2856.             LAST_HistoryLines (LONG) - Number of lines to keep as
  2857.                 a backlog.
  2858.                 Default: 0
  2859.  
  2860.             LAST_HistoryHook (struct Hook *) - Hook code to call
  2861.                 when entering a line into the backlog. See gtlayout.h
  2862.                 for more information.
  2863.                 Default: NULL
  2864.  
  2865.             LAST_Activate (BOOL) - When the window opens, make this
  2866.                 gadget the active one. (V21)
  2867.  
  2868.                     NOTE: There can be only one gadget of this type
  2869.                         per window.
  2870.  
  2871.                 Default: FALSE
  2872.  
  2873.  
  2874.         TAB_KIND:
  2875.  
  2876.             (This features requires gtlayout.library v24 or higher)
  2877.  
  2878.             LATB_FirstLabel (LONG) - Locale string ID of the first
  2879.                 text to use as a label. Works in conjunction
  2880.                 with LATB_LastLabel.
  2881.  
  2882.             LATB_LastLabel (LONG) - Locale string ID of the last
  2883.                 text to use as a label. Works in conjunction
  2884.                 with LATB_FirstLabel. When building the interface the
  2885.                 code will loop from FirstLabel..LastLabel, look
  2886.                 up the corresponding locale strings and use the
  2887.                 data to make up the label text.
  2888.  
  2889.             LATB_LabelTable (LONG *) - Pointer to an array of IDs
  2890.                 to use for building the cycle labels. This requires
  2891.                 that a locale hook is provided with the layout handle.
  2892.                 The array is terminated by -1.
  2893.  
  2894.             LATB_TabKey (BOOL) - Connect this object to the tabulator
  2895.                 key. Press [Tab] to cycle to the next entry, [Shift][Tab]
  2896.                 to cycle to the previous entry.
  2897.  
  2898.                     NOTE: there can be only one single button per
  2899.                         window to use this feature.
  2900.  
  2901.                 Default: FALSE
  2902.  
  2903.             LATB_AutoPageID (LONG) - ID of paged GROUP_KIND object
  2904.                 which will be set to the gadget's current setting.
  2905.                 If this tag is set, you will hear no events from this
  2906.                 object any more.
  2907.  
  2908.                     NOTE: Listen to IDCMP_CLOSEWINDOW events
  2909.                         which may be generated if the layout
  2910.                         engine runs out of memory when rebuilding
  2911.                         the user interface.
  2912.  
  2913.             LATB_FullSize (BOOL) - By default a TAB_KIND object
  2914.                 covers the entire width of the group it sits in.
  2915.                 With LATB_FullSize set to true it will cover the
  2916.                 width of the entire Window.
  2917.  
  2918.                 Default: FALSE
  2919.  
  2920.             LATB_Labels (STRPTR *) - Pointer to NULL-terminated array
  2921.                 of strings that are the choices offered.
  2922.  
  2923.  
  2924.         TAPEDECK_KIND:
  2925.  
  2926.             LATD_ButtonType (LONG) - Select the image to display
  2927.                 in the button, must be one of the following:
  2928.  
  2929.                     TDBT_BACKWARD
  2930.                         "<<" Symbol
  2931.  
  2932.                     TDBT_FORWARD
  2933.                         ">>" Symbol
  2934.  
  2935.                     TDBT_PREVIOUS
  2936.                         "|<" Symbol
  2937.  
  2938.                     TDBT_NEXT
  2939.                         ">|" Symbol
  2940.  
  2941.                     TDBT_STOP
  2942.                         Stop symbol (filled square)
  2943.  
  2944.                     TDBT_PAUSE
  2945.                         "||" pause symbol (broken square)
  2946.  
  2947.                     TDBT_RECORD
  2948.                         Record symbol (filled circle)
  2949.  
  2950.                     TDBT_REWIND
  2951.                         "<" symbol
  2952.  
  2953.                     TDBT_EJECT
  2954.                         Eject symbol (broken upward pointing arrow)
  2955.  
  2956.                     TDBT_PLAY
  2957.                         ">" symbol
  2958.  
  2959.             LATD_Toggle (BOOL) - Make this object a toggle-select
  2960.                 button.
  2961.                 Default: FALSE
  2962.  
  2963.             LATD_Pressed (BOOL) - Make this button appear to be
  2964.                 pressed.
  2965.  
  2966.                     NOTE: requires "LATD_Toggle,TRUE" attribute.
  2967.  
  2968.                 Default: FALSE
  2969.  
  2970.             LATD_Smaller (BOOL) - Make this button a bit smaller
  2971.                 than usual.
  2972.                 Default: FALSE
  2973.  
  2974.             LATD_Tick (BOOL) - Hear IDCMP_GADGETUP events while the
  2975.                 buttons is being pressed; the IntuiMessage->Code entry
  2976.                 will be 0 while the button is being pressed, and
  2977.                 will be 1 as soon as the button is released. (V12)
  2978.  
  2979.                 Default: FALSE
  2980.  
  2981.  
  2982.         TEXT_KIND:
  2983.  
  2984.             LATX_Picker (BOOL) - Attach a `select' button to the
  2985.                 right hand side of the text display.
  2986.                 Default: FALSE
  2987.  
  2988.             LATX_LockSize (BOOL) - After doing the initial layout
  2989.                 for this object, do not adapt its size again during
  2990.                 subsequent layouts. This is particularly useful if
  2991.                 you have a TEXT_KIND object in a paged group
  2992.                 and update its contents later. You need
  2993.                 to specify an object width using LA_Chars, otherwise
  2994.                 the layout engine may make it not wide enough to
  2995.                 display any text. (V15)
  2996.  
  2997.  
  2998.         VERTICAL_KIND (group to align objects vertically):
  2999.         HORIZONTAL_KIND (group to align objects horizontally):
  3000.  
  3001.             LAGR_Spread (BOOL) - Place all objects in this
  3002.                 group with roughly the same amount of space
  3003.                 between them.
  3004.                 Default: FALSE
  3005.  
  3006.             LAGR_SameSize (BOOL) - Make all objects in this
  3007.                 group the same size (for vertical groups:
  3008.                 the same height, for horizontal groups:
  3009.                 the same width).
  3010.                 Default: FALSE
  3011.  
  3012.             LAGR_LastAttributes (BOOL) - Try to copy the
  3013.                 size of the previous group for this new
  3014.                 group. May not work if this group turns
  3015.                 out to be larger than the previous group.
  3016.                 Default: FALSE
  3017.  
  3018.             LAGR_ActivePage (LONG) - Organize all child
  3019.                 groups as pages which can be flipped through
  3020.                 using LT_SetAttributes(). You need to
  3021.                 specify the number of the first page to
  3022.                 display, starting from 0.
  3023.  
  3024.                     NOTE: Specifying this tag actually enables
  3025.                         the paging feature. If you omit this
  3026.                         tag calls to flip to a specific
  3027.                         page will fail.
  3028.  
  3029.                 Default: No paging
  3030.  
  3031.             LAGR_Frame (BOOL) - Draw a recessed frame around
  3032.                 this group, even if there is no group label. (V7)
  3033.  
  3034.             LAGR_IndentX (BOOL) - Add extra horizontal indentation
  3035.                 for this group. (V10)
  3036.  
  3037.             LAGR_IndentY (BOOL) - Add extra vertical indentation
  3038.                 for this group. (V10)
  3039.  
  3040.             LAGR_NoIndent (BOOL) - Inhibit automatic size adjustion
  3041.                 and centring of this group if it is smaller than
  3042.                 the neighbouring groups. (V21)
  3043.  
  3044.             LAGR_SameWidth (WORD) - During the final layout pass,
  3045.                 make this group the same width as the group which
  3046.                 uses the given ID. Not implemented yet. (V25)
  3047.  
  3048.             LAGR_SameHeight (WORD) - During the final layout pass,
  3049.                 make this group the same height as the group which
  3050.                 uses the given ID. Not implemented yet. (V25)
  3051.  
  3052.             LAGR_FrameGroup (UWORD) - Surround this group with a
  3053.                 frame. Must be one of FRAMETYPE_Label or FRAMETYPE_Tab.
  3054.                 FRAMETYPE_Label works like "LAGR_Frame,TRUE," while
  3055.                 FRAMETYPE_Tab is for use with a TAB_KIND object you
  3056.                 must put directly on top of this group or the group
  3057.                 will look a little silly. (V38)
  3058.  
  3059.                 Default: FRAMETYPE_None
  3060.  
  3061.  
  3062.         XBAR_KIND (horizontal separator bar):
  3063.  
  3064.             LAXB_FullSize (BOOL) - Make this separator bar span
  3065.                 the entire window width.
  3066.  
  3067.  
  3068.         YBAR_KIND (vertical separator bar):
  3069.  
  3070.             No tags are defined for this type of object.
  3071.  
  3072.  
  3073.    RESULT
  3074.     none
  3075.  
  3076.    BUGS
  3077.     Up to v25 the SCROLLER_KIND object did not support GA_Immediate
  3078.     or GA_RelVerify. The space for the variables was there, but the
  3079.     code was missing.
  3080.  
  3081.     POPUP_KIND objects don't work well in simple refresh windows,
  3082.     as refresh events can get lost. Use a smart refresh window
  3083.     instead or call gadtools.library/LT_CatchUpRefresh() regularly.
  3084.  
  3085.    SEE ALSO
  3086.     gadtools.library/CreateGadgetA
  3087.  
  3088. gtlayout.library/LT_NewLevelWidth           gtlayout.library/LT_NewLevelWidth
  3089.  
  3090.    NAME
  3091.     LT_NewLevelWidth -- Determine the maximum width of a SLIDER_KIND
  3092.                         level string. (V14)
  3093.  
  3094.    SYNOPSIS
  3095.     Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
  3096.       D0                    A0        A1         A2     D0  D1    A3
  3097.  
  3098.                               MaxLen,FullCheck);
  3099.                                 D3      D2
  3100.  
  3101.     LONG LT_LevelWidth(LayoutHandle *,STRPTR,
  3102.                        LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
  3103.                        LONG *,BOOL);
  3104.  
  3105.    FUNCTION
  3106.     In order to make room for the level text displayed by a
  3107.     SLIDER_KIND object one needs to know how much space the
  3108.     longest level string will occupy. Otherwise, the level
  3109.     text may overwrite the gadget label text or the slider
  3110.     container. This routine will rattle through all possible
  3111.     slider settings (as given via the Min and the Max
  3112.     level values) and determine the longest label string
  3113.     according to the font used.
  3114.  
  3115.    INPUTS
  3116.     Handle - Pointer to a LayoutHandle structure, as returned by
  3117.         a call to LT_CreateHandleTags().
  3118.  
  3119.     FormatString - The sprintf() style formatting string to be used
  3120.         to format the slider level settings into text.
  3121.         This is the same string you would pass in via
  3122.         the GTSL_LevelFormat tag when creating the
  3123.         slider object.
  3124.         Default: "%lD" for systems which have locale.library
  3125.             installed, "%ld" otherwise.
  3126.  
  3127.     DispFunc - A pointer to the function to filter the slider level
  3128.         values. The result of this function will then be
  3129.         used to format a string into the slider level text.
  3130.         This is the same parameter you would pass in via
  3131.         the GTSL_DispFunc tag when creating the slider
  3132.         object.
  3133.  
  3134.         NOTE: the routine will be called with a NULL Gadget
  3135.             parameter, make sure your code will handle
  3136.             this nicely.
  3137.  
  3138.         Default: no display function
  3139.  
  3140.     Min - The smallest value the slider can be set to. This is
  3141.         same value you would pass in via GTSL_Min when creating
  3142.         the slider object.
  3143.  
  3144.     Max - The largest value the slider can be set to. This is
  3145.         same value you would pass in via GTSL_Max when creating
  3146.         the slider object.
  3147.  
  3148.     MaxWidth - Pointer to a place to store the width of the
  3149.         longest level string in pixels. If you pass
  3150.         in NULL instead of the address of a variable
  3151.         no harm will be done.
  3152.  
  3153.     MaxLen - Pointer to a place to store the length of the
  3154.         longest level string in characters. If you pass
  3155.         in NULL instead of the address of a variable
  3156.         no harm will be done.
  3157.  
  3158.     FullCheck - TRUE will cause the code to rattle through all
  3159.         possible slider settings, starting from the
  3160.         minimum value, ending at the maximum value.
  3161.         While this may be a good idea for a display
  3162.         function to map slider levels to text strings
  3163.         of varying length it might be a problem when
  3164.         it comes to display a range of numbers from
  3165.         1 to 40,000: the code will loop through
  3166.         40,000 iterations trying to find the longest
  3167.         string.
  3168.  
  3169.         FALSE will cause the code to calculate the
  3170.         longest level string based only on the
  3171.         minimum and the maximum value to check.
  3172.         While this is certainly a good a idea when
  3173.         it comes to display a range of numbers from
  3174.         1 to 40,000 as only two values will be
  3175.         checked the code may fail to produce
  3176.         accurate results for sliders using display
  3177.         functions mapping slider levels to strings.
  3178.  
  3179.    RESULT
  3180.     Index - The slider level which gives the longest
  3181.         level string.
  3182.  
  3183.    NOTES
  3184.     This function does exactly what gtlayout.library/LT_LevelWidth
  3185.     does, but uses a slightly different register ordering. Namely,
  3186.     the MaxLen pointer is passed in D3 instead of A5.
  3187.  
  3188.    SEE ALSO
  3189.     gtlayout.library/LT_LevelWidth
  3190.  
  3191. gtlayout.library/LT_NewMenuTagList         gtlayout.library/LT_NewMenuTagList
  3192.  
  3193.    NAME
  3194.     LT_NewMenuTagList -- Allocate and layout menu items (V11)
  3195.  
  3196.    SYNOPSIS
  3197.     Menu = LT_NewMenuTagList(Tags)
  3198.      D0                       A0
  3199.  
  3200.     struct Menu *LT_NewMenuTagList(struct TagItem *);
  3201.  
  3202.     struct Menu *LT_NewMenuTags(...);
  3203.  
  3204.    FUNCTION
  3205.     Allocates Menus and MenuItems similar to LT_LayoutMenus().
  3206.  
  3207.     As of v18 this routine will validate menu mutual exclusion
  3208.     information.
  3209.  
  3210.    INPUTS
  3211.     Tags - Pointer to a list of tagitem values, as found
  3212.         in gtlayout.h
  3213.  
  3214.  
  3215.     Valid tags include:
  3216.  
  3217.     LAMN_Screen (struct Screen *) - Pointer to the Screen
  3218.         the menu is to appear upon. This tag is mandatory,
  3219.         unless the LAMN_LayoutHandle tag is used.
  3220.  
  3221.     LAMN_TextAttr (struct TextAttr *) - Pointer to the
  3222.         TextAttr to use for the menu layout. If this tag
  3223.         is omitted the Screen->Font will be used.
  3224.  
  3225.     LAMN_Error (LONG *) - Pointer to variable to receive
  3226.         an error in case of failure.
  3227.  
  3228.     LAMN_AmigaGlyph (struct Image *) - Pointer to Image to
  3229.         use as the Amiga glyph in menus. Will be ignored if
  3230.         NULL.
  3231.  
  3232.         NOTE: Ignored by intuition.library v37 and below.
  3233.  
  3234.     LAMN_CheckmarkGlyph (struct Image *) - Pointer to Image to
  3235.         use as the checkmark glyph in menus. Will be ignored
  3236.         if NULL.
  3237.  
  3238.     LAMN_LayoutHandle (LayoutHandle *) - Pointer to a valid
  3239.         LayoutHandle as created by LT_CreateHandle. This tag
  3240.         provides all the information the single tags
  3241.         LAMN_Screen..LAMN_CheckmarkGlyph would otherwise
  3242.         need to provide.
  3243.  
  3244.     LAMN_TitleText (STRPTR) - Name of new menu to create.
  3245.         You may precede the name with the keyboard shortcut
  3246.         to assign to this menu item as follows:
  3247.  
  3248.            A\0Save as...
  3249.  
  3250.         This will create a menu item using the shortcut "A"
  3251.         and the title "Save as...".
  3252.  
  3253.     LAMN_TitleID (LONG) - Locale ID corresponding to the
  3254.         name of the new menu to create.
  3255.         You may precede the name with the keyboard shortcut
  3256.         to assign to this menu item as follows:
  3257.  
  3258.            A\0Save as...
  3259.  
  3260.         This will create a menu item using the shortcut "A"
  3261.         and the title "Save as...".
  3262.  
  3263.     LAMN_ItemText (STRPTR) - Name of new menu item to create.
  3264.         You may precede the name with the keyboard shortcut
  3265.         to assign to this menu item as follows:
  3266.  
  3267.            A\0Save as...
  3268.  
  3269.         This will create a menu item using the shortcut "A"
  3270.         and the title "Save as...".
  3271.  
  3272.     LAMN_ItemID (LONG) - Locale ID corresponding to the
  3273.         name of the new menu item to create.
  3274.         You may precede the name with the keyboard shortcut
  3275.         to assign to this menu item as follows:
  3276.  
  3277.            A\0Save as...
  3278.  
  3279.         This will create a menu item using the shortcut "A"
  3280.         and the title "Save as...".
  3281.  
  3282.     LAMN_SubText (STRPTR) - Name of new submenu item to create.
  3283.         You may precede the name with the keyboard shortcut
  3284.         to assign to this menu item as follows:
  3285.  
  3286.            A\0Save as...
  3287.  
  3288.         This will create a menu item using the shortcut "A"
  3289.         and the title "Save as...".
  3290.  
  3291.     LAMN_SubID (LONG) - Locale ID corresponding to the
  3292.         name of the new submenu item to create.
  3293.         You may precede the name with the keyboard shortcut
  3294.         to assign to this menu item as follows:
  3295.  
  3296.            A\0Save as...
  3297.  
  3298.         This will create a menu item using the shortcut "A"
  3299.         and the title "Save as...".
  3300.  
  3301.     LAMN_KeyText (STRPTR) - Pointer to the string whose first
  3302.         character will be used as the keyboard shortcut for
  3303.         this menu/submenu item.
  3304.  
  3305.     LAMN_KeyID (LONG) - Locale ID corresponding to the string whose
  3306.         first character will be used as the keyboard shortcut for
  3307.         this menu/submenu item.
  3308.  
  3309.     LAMN_CommandText (STRPTR) - Pointer to the string which
  3310.         will be used as the keyboard shortcut for this
  3311.         menu/submenu item.
  3312.  
  3313.     LAMN_CommandID (LONG) - Locale ID corresponding to the string
  3314.         which will be used as the keyboard shortcut for
  3315.         this menu/submenu item.
  3316.  
  3317.     LAMN_MutualExclude (ULONG) - Mutual exclusion information for
  3318.         this menu/submenu item.
  3319.  
  3320.     LAMN_UserData (APTR) - User data information for this
  3321.         menu/menu item/submenu item.
  3322.  
  3323.     LAMN_Disabled (BOOL) - Controls whether this
  3324.         menu/menu item/submenu item should be disabled.
  3325.  
  3326.     LAMN_CheckIt (BOOL) - Controls whether this menu/submenu item
  3327.         should be prepared to hold a checkmark.
  3328.  
  3329.             NOTE: This does not set the checkmark, use LAMN_Checked
  3330.                 for this purpose.
  3331.  
  3332.     LAMN_Checked (BOOL) - Controls whether this menu/submenu item
  3333.         should be marked with a checkmark. This tag implies
  3334.         "LAMN_CheckIt,TRUE".
  3335.  
  3336.     LAMN_Toggle (BOOL) - Controls whether this menu/submenu item
  3337.         should be prepared to hold a checkmark the user is to
  3338.         toggle on demand. This tag implies "LAMN_CheckIt,TRUE".
  3339.  
  3340.             NOTE: this does not set the checkmark, use LAMN_Checked
  3341.                 for this purpose.
  3342.  
  3343.     LAMN_Code (UWORD) - Raw key code to associate with this
  3344.         menu/submenu item. To find out if a rawkey event
  3345.         corresponds to this menu item use LT_FindMenuCommand.
  3346.  
  3347.     LAMN_Qualifier (ULONG) - Key qualifier to associate
  3348.         with this menu/submenu item.
  3349.  
  3350.             NOTE: the comparison does not distinguish between
  3351.                 the left and right shift/caps/alt qualifier keys.
  3352.  
  3353.     LAMN_ID (ULONG) - Unique ID to associate with this
  3354.         menu/menu item/submenu item. You can use this
  3355.         later to look up data using LT_GetMenuItem, etc.
  3356.  
  3357.     LAMN_ExtraSpace (UWORD) - Number of pixels to put between
  3358.         neighbouring menu titles. (V18)
  3359.         Default: 0 pixels.
  3360.  
  3361.    RESULT
  3362.     Menu - Pointer to Menu structure, ready to pass to
  3363.            SetMenuStrip(), NULL on failure.
  3364.  
  3365.    EXAMPLE
  3366.     The following tagitem list:
  3367.  
  3368.         LAMN_TitleText,     "Project"
  3369.          LAMN_ItemText,     "New",
  3370.           LAMN_KeyText,     "N",
  3371.          LAMN_ItemText,     "Open...",
  3372.           LAMN_KeyText,     "O",
  3373.          LAMN_ItemText,     NM_BARLABEL,
  3374.          LAMN_ItemText,     "Save",
  3375.           LAMN_KeyText,     "S",
  3376.          LAMN_ItemText,     "A\0Save As...",
  3377.          LAMN_ItemText,     NM_BARLABEL,
  3378.          LAMN_ItemText,     "Print...",
  3379.           LAMN_KeyText,     "P",
  3380.          LAMN_ItemText,     NM_BARLABEL,
  3381.          LAMN_ItemText,     "Help...",
  3382.           LAMN_CommandText, "[Help]",
  3383.          LAMN_ItemText,     NM_BARLABEL,
  3384.          LAMN_ItemText,     "Quit...",
  3385.           LAMN_KeyText,     "Q",
  3386.         TAG_DONE
  3387.  
  3388.     Will create the following menu:
  3389.  
  3390.     +-------+
  3391.     |Project|
  3392.     +-------+------+
  3393.     |New         aN|
  3394.     |Open...     aO|
  3395.     |~~~~~~~~~~~~~~|
  3396.     |Save        aS|
  3397.     |Save As...  aA|
  3398.     |~~~~~~~~~~~~~~|
  3399.     |Print...    aP|
  3400.     |~~~~~~~~~~~~~~|
  3401.     |Help... [Help]|
  3402.     |~~~~~~~~~~~~~~|
  3403.     |Quit...     aQ|
  3404.     +--------------+
  3405.  
  3406.    NOTES
  3407.     You may freely add, remove, spindle & mutilate the contents of the
  3408.     menu strip created, just don't trash or disconnect the base menu
  3409.     entry this routine creates as all menu memory tracking data is
  3410.     connected to it.
  3411.  
  3412.    SEE ALSO
  3413.     gtlayout.library/LT_DisposeMenu
  3414.     gtlayout.library/LT_FindCommandItem
  3415.     gtlayout.library/LT_GetMenuItem
  3416.     gtlayout.library/LT_LayoutMenuA
  3417.     gtlayout.library/LT_MenuControlTagList
  3418.     gtlayout.library/LT_NewMenuTemplate
  3419.     intuition.library/SetMenuStrip
  3420.  
  3421. gtlayout.library/LT_NewMenuTemplate       gtlayout.library/LT_NewMenuTemplate
  3422.  
  3423.    NAME
  3424.     LT_NewMenuTemplate -- Allocate and layout menu items (V11)
  3425.  
  3426.    SYNOPSIS
  3427.     Menu = LT_NewMenuTemplate(Screen,TextAttr,AmigaGlyph,CheckmarkGlyph,
  3428.      D0                         A0      A1        A2           A3
  3429.  
  3430.                               Error,MenuTemplate);
  3431.                                 D0      D1
  3432.  
  3433.     struct Menu *LT_NewMenuTemplate(struct Screen *,struct TextAttr *,
  3434.                                     struct Image *,struct Image *,
  3435.                                     LONG *,struct NewMenu *);
  3436.  
  3437.    FUNCTION
  3438.     Allocates Menus and MenuItems similar to LT_LayoutMenus().
  3439.  
  3440.     As of v18 this routine will validate menu mutual exclusion
  3441.     information.
  3442.  
  3443.    INPUTS
  3444.     Screen - Pointer to the screen the menu will appear on. This
  3445.         parameter is required and must not be omitted.
  3446.  
  3447.     TextAttr - Pointer to the TextAttr that should be used to
  3448.         layout the menus. If this parameter is omitted,
  3449.         Screen->Font will be used instead.
  3450.  
  3451.     AmigaGlyph - Pointer to the Image to use as the Amiga glyph.
  3452.         This parameter may be omitted.
  3453.  
  3454.             NOTE: Ignored by intuition.library v37 and below.
  3455.  
  3456.     CheckmarkGlyph - Pointer to the Image to use as the checkmark
  3457.         glyph. This parameter may be omitted.
  3458.  
  3459.     Error - Pointer to receive error code in case the menu
  3460.         creation or layout process fails. This parameter
  3461.         may be omitted.
  3462.  
  3463.     MenuTemplate - Pointer to a series of NewMenu structures,
  3464.         just as you would pass to
  3465.         gtlayout.library/LT_LayoutMenuA.
  3466.  
  3467.    RESULT
  3468.     Menu - Pointer to Menu structure, ready to pass to
  3469.         SetMenuStrip(), NULL on failure.
  3470.  
  3471.    NOTES
  3472.     The menu created by this function cannot be used with the
  3473.     routines LT_MenuControlTagList, LT_FindMenuCommand and
  3474.     LT_GetMenuItem.
  3475.  
  3476.     You may freely add, remove, spindle & mutilate the contents of the
  3477.     menu strip created, just don't trash or disconnect the base menu
  3478.     entry this routine creates as all menu memory tracking data is
  3479.     connected with it.
  3480.  
  3481.    SEE ALSO
  3482.     gtlayout.library/LT_DisposeMenu
  3483.     gtlayout.library/LT_LayoutMenuA
  3484.     gtlayout.library/LT_NewMenuTagList
  3485.     intuition.library/SetMenuStrip
  3486.  
  3487. gtlayout.library/LT_PressButton               gtlayout.library/LT_PressButton
  3488.  
  3489.    NAME
  3490.     LT_PressButton -- Highlight a button so it looks as if the user
  3491.                       has selected it.
  3492.  
  3493.    SYNOPSIS
  3494.     Success = LT_PressButton(Handle,ID);
  3495.        D0                       A0  D0
  3496.  
  3497.     BOOL LT_PressButton(LayoutHandle *,LONG);
  3498.  
  3499.         NOTE: The return value did not exist until V39!
  3500.  
  3501.    FUNCTION
  3502.     You can provide visual feedback for BUTTON_KIND objects by calling
  3503.     this routine. They will briefly appear to be selected and then
  3504.     fall back to their original states.
  3505.  
  3506.     As of V39 and beyond this function will indicate whether the button
  3507.     could be highlighted or not.
  3508.  
  3509.    INPUTS
  3510.     Handle - Pointer to LayoutHandle structure
  3511.  
  3512.     ID - ID of button object to highlight
  3513.  
  3514.    RESULT
  3515.     Success (V39) - TRUE if button could be highlighted, FALSE otherwise.
  3516.  
  3517. gtlayout.library/LT_RebuildTagList         gtlayout.library/LT_RebuildTagList
  3518.  
  3519.    NAME
  3520.     LT_RebuildTagList -- Rebuild the user interface after modifying it.
  3521.  
  3522.    SYNOPSIS
  3523.     Success = LT_RebuildTagList(Handle,Clear,TagList);
  3524.        D0                         A0    D0     A1
  3525.  
  3526.     BOOL LT_RebuildTagList(LayoutHandle *,BOOL,struct TagItem *);
  3527.  
  3528.     Success = LT_RebuildTags(Handle,Clear,...);
  3529.  
  3530.     BOOL LT_RebuildTags(LayoutHandle *,BOOL,...);
  3531.  
  3532.    FUNCTION
  3533.     Certain aspects of the user interface can be changed at run time,
  3534.     such as button labels. This routine will let you rebuild the interface
  3535.     based upon the data supplied at creation time and your subsequent
  3536.     changes. Before you make any vital changes, it is recommended to
  3537.     lock the window using LT_LockWindow() in order to avoid clashes
  3538.     with the Intuition and GadTools subsystems.
  3539.  
  3540.    INPUTS
  3541.     Handle - Pointer to LayoutHandle structure.
  3542.  
  3543.     Clear - Pass in TRUE if you wish to have the window contents
  3544.         cleared before they are rebuild. This will introduce
  3545.         some visual hashing.
  3546.  
  3547.     TagList - Attributes controlling the layout process.
  3548.  
  3549.  
  3550.     Valid tags include:
  3551.  
  3552.     LAWN_Bounds (struct IBox *) - Boundaries in which the window
  3553.         should be centered.
  3554.  
  3555.     LAWN_ExtraWidth (LONG) - Extra space to add to the window
  3556.         width.
  3557.  
  3558.     LAWN_ExtraHeight (LONG) - Extra height to add to the window
  3559.         height.
  3560.  
  3561.    RESULT
  3562.     Success - TRUE indicates that the interface was rebuilt,
  3563.         FALSE indicates trouble; it is recommended to
  3564.         call LT_DeleteHandle() on your LayoutHandle as
  3565.         soon as possible as the previous operation may
  3566.         have left the user interface in an inoperable
  3567.         state.
  3568.  
  3569. gtlayout.library/LT_Refresh                       gtlayout.library/LT_Refresh
  3570.  
  3571.    NAME
  3572.     LT_Refresh -- Redraws the entire window contents.
  3573.  
  3574.    SYNOPSIS
  3575.     LT_Refresh(Handle)
  3576.                  A0
  3577.  
  3578.     VOID LT_Refresh(LayoutHandle *);
  3579.  
  3580.    FUNCTION
  3581.     Redraws the contents of the window, this includes both gadgets
  3582.     and imagery.
  3583.  
  3584.    INPUTS
  3585.     Handle - Pointer to a LayoutHandle structure.
  3586.  
  3587.    RESULT
  3588.     none
  3589.  
  3590.    SEE ALSO
  3591.        gadtools.library/GT_RefreshWindow
  3592.        intuition.library/RefreshGList
  3593.  
  3594. gtlayout.library/LT_ReplyIMsg                   gtlayout.library/LT_ReplyIMsg
  3595.  
  3596.    NAME
  3597.     LT_ReplyIMsg -- Dispose of an IntuiMessage received
  3598.  
  3599.    SYNOPSIS
  3600.     LT_ReplyIMsg(IntuiMessage);
  3601.                      A0
  3602.  
  3603.     VOID LT_ReplyIMsg(struct IntuiMessage *);
  3604.  
  3605.    FUNCTION
  3606.     This routine complements LT_GetIMsg().
  3607.  
  3608.    INPUTS
  3609.     IntuiMessage - Pointer to IntuiMessage structure,
  3610.         passing NULL is harmless.
  3611.  
  3612.    RESULT
  3613.     none
  3614.  
  3615.    NOTES
  3616.     Only pass IntuiMessages you received via LT_GetIMsg,
  3617.     or things will get tough.
  3618.  
  3619.    SEE ALSO
  3620.     gtlayout.library/LT_GetIMsg
  3621.  
  3622. gtlayout.library/LT_SetAttributesA         gtlayout.library/LT_SetAttributesA
  3623.  
  3624.    NAME
  3625.     LT_SetAttributesA -- Change object attributes
  3626.  
  3627.    SYNOPSIS
  3628.     LT_SetAttributesA(Handle,ID,Tags);
  3629.                         A0   D0  A1
  3630.  
  3631.     VOID LT_SetAttributes(LayoutHandle *,LONG,struct TagItem *);
  3632.  
  3633.     LT_SetAttributes(Handle,ID,...);
  3634.  
  3635.     VOID LT_SetAttributes(LayoutHandle *,LONG,...);
  3636.  
  3637.    FUNCTION
  3638.     This routine passes the tag item list it gets directly
  3639.     over to GT_SetGadgetAttrsA(), so any tag items valid for
  3640.     gadtools.library can be used here as well. Some filtering
  3641.     may be done in order to stop objects from getting redrawn
  3642.     if this is not absolutely necessary.
  3643.  
  3644.    INPUTS
  3645.     Handle - Pointer to LayoutHandle.
  3646.  
  3647.     ID - ID number of the object to change. This is the same value
  3648.         you passed via LA_ID to LT_New() when you created this object.
  3649.  
  3650.     Tags - Attributes controlling object states.
  3651.  
  3652.  
  3653.     All gadtools.library tags are allowed, but not all are supported.
  3654.     In addition to these tags a few additional tag values are
  3655.     supported:
  3656.  
  3657.     LAHN_AutoActivate (BOOL) - Set to TRUE if you want the interface
  3658.         to always keep a string gadget active if possible. Hitting
  3659.         the return key will then cause the next following string
  3660.         gadget to get activated, either cycling through all the
  3661.         string gadgets available or stopping at the next string
  3662.         gadget to have the LAST_LastGadget attribute set.
  3663.  
  3664.     LAHN_UserData (APTR) - Store user specific data in the
  3665.         LayoutHandle->UserData entry. (V9)
  3666.  
  3667.     LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
  3668.         events. (V13)
  3669.         Default: TRUE
  3670.  
  3671.     LAHN_LocaleHook (struct Hook *) - The hook to call when
  3672.         locale string IDs are to be mapped to strings. The
  3673.         hook function is called with the following parameters:
  3674.  
  3675.         String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
  3676.           D0                            A0                         A2
  3677.                           LONG ID)
  3678.                                A1
  3679.  
  3680.         The function is to look up the string associated with the ID
  3681.         passed in and return the string.
  3682.  
  3683.     LAHN_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
  3684.         of with LT_DeleteHandle() all variables maintained by the
  3685.         input handling code will be flushed. For example, if you
  3686.         would use the LA_STRPTR tag for STRING_KIND objects the
  3687.         last string gadget contents would be copied into the buffer
  3688.         pointed to by LA_STRPTR. If you do not want to use this
  3689.         feature, disable it with "LAHN_ExitFlush,FALSE". (V9)
  3690.         Default: TRUE
  3691.  
  3692.     GAUGE_KIND:
  3693.  
  3694.         LAGA_Percent (LONG) - Percentage of the gauge to fill.
  3695.  
  3696.         LAGA_InfoText (STRPTR) - Text to be printed within the
  3697.             gauge display, such as a percentage number.
  3698.  
  3699.     BOX_KIND:
  3700.  
  3701.         LABX_Index (LONG) - The number of the line to change, this
  3702.             tag works in conjunction with the LABX_Text tag.
  3703.  
  3704.         LABX_Text (STRPTR) - The text to put into the line indicated
  3705.             by the LABX_Index tag.
  3706.             As of v26 the LABX_Index tag may be omitted, the library
  3707.             will then assume the line index will be 0.
  3708.  
  3709.         LABX_Lines (STRPTR *) - The text to set for the box contents,
  3710.             terminate the text array with NULL.
  3711.  
  3712.     HORIZONTAL_KIND:
  3713.     VERTICAL_KIND:
  3714.  
  3715.         LAGR_ActivePage (LONG) - Index number of page to display
  3716.             within the group.
  3717.  
  3718.                 NOTE: requires that this group was created
  3719.                     with the LAGR_ActivePage attribute set.
  3720.  
  3721.     INTEGER_KIND:
  3722.  
  3723.         LAIN_Min (LONG) - Minimum allowed value for this
  3724.             object.
  3725.  
  3726.         LAIN_Max (LONG) - Maximum allowed value for this
  3727.             object.
  3728.  
  3729.     LISTVIEW_KIND:
  3730.  
  3731.         LALV_Selected (LONG) - Combines GTLV_Selected and
  3732.             GTLV_Top (for Kickstart V37) or GTLV_MakeVisible
  3733.             (for Kickstart V39 and greater). This means, the
  3734.             list display will be changed in order to show
  3735.             the item to be selected. (V34)
  3736.  
  3737.     LEVEL_KIND:
  3738.  
  3739.         LAVL_NumTicks (WORD) - Number of tick marks to draw
  3740.            next to the slider body.
  3741.  
  3742.     PASSWORD_KIND:
  3743.  
  3744.         LAPW_String (STRPTR) - Secret text to use
  3745.  
  3746.     POPUP_KIND
  3747.  
  3748.         LAPU_Labels (STRPTR *) - To block access to the popup
  3749.             menu, for example before you free the current list
  3750.             of labels, you can pass ~0 as the list parameter. (V25)
  3751.  
  3752.     STRING_KIND:
  3753.  
  3754.         LAST_CursorPosition (LONG) - Repositions the cursor,
  3755.             pass -1 to move it to the end of the string. (V7)
  3756.  
  3757.     TAPEDECK_KIND:
  3758.  
  3759.         LATD_Pressed (BOOL) - TRUE to make this button shown
  3760.             as pressed, FALSE to show it in depressed state.
  3761.  
  3762.     BOOPSI_KIND:
  3763.  
  3764.         All tags are passed straight through to SetGadgetAttrs(..).
  3765.  
  3766.     All objects:
  3767.  
  3768.         LA_LabelText (STRPTR) - New gadget label text to use.
  3769.  
  3770.         LA_LabelID (LONG) - Locale text ID to use for this object.
  3771.  
  3772.    RESULT
  3773.     none
  3774.  
  3775.    SEE ALSO
  3776.     gadtools.library/GT_SetGadgetAttrsA()
  3777.     intuition.library/SetGadgetAttrsA
  3778.  
  3779. gtlayout.library/LT_ShowWindow                 gtlayout.library/LT_ShowWindow
  3780.  
  3781.    NAME
  3782.     LT_ShowWindow -- Make a window visible
  3783.  
  3784.    SYNOPSIS
  3785.     LT_ShowWindow(Handle,Activate);
  3786.                     A0      A1
  3787.  
  3788.     VOID LT_ShowWindow(LayoutHandle *,BOOL);
  3789.  
  3790.    FUNCTION
  3791.     The window attached to a LayoutHandle is made visible, this
  3792.     involves bringing it to the front, bringing the screen to
  3793.     the front the window resides on, unzooming the window and
  3794.     also moving the visible part of an autoscrolling screen.
  3795.  
  3796.    INPUTS
  3797.     Window - Pointer to Window structure.
  3798.  
  3799.     Activate - If TRUE the window will be activated as soon
  3800.         as it has been brought to the front.
  3801.  
  3802.    RESULT
  3803.     none
  3804.  
  3805.    NOTES
  3806.     The arguments are passed in A0 and A1, this is *not* a
  3807.     typo.
  3808.  
  3809.    BUGS
  3810.     In revisions earlier than v21 this routine consistently
  3811.     failed to reliably unzip a window in zoomed state. This
  3812.     could cause the calling application to wait for about
  3813.     five seconds before continuing execution.
  3814.  
  3815.    SEE ALSO
  3816.     intuition.library/MoveScreen
  3817.     intuition.library/ScreenPosition
  3818.     intuition.library/ZipWindow
  3819.  
  3820. gtlayout.library/LT_UnlockWindow             gtlayout.library/LT_UnlockWindow
  3821.  
  3822.    NAME
  3823.     LT_UnlockWindow -- The complement to LT_LockWindow().
  3824.  
  3825.    SYNOPSIS
  3826.     LT_UnlockWindow(Window);
  3827.                       A0
  3828.  
  3829.     VOID LT_UnlockWindow(struct Window *);
  3830.  
  3831.    FUNCTION
  3832.     This routine unlocks a window locked using LT_LockWindow, freeing
  3833.     allocated memory, restoring the window characteristics to their
  3834.     original values.
  3835.  
  3836.    INPUTS
  3837.     Window - Pointer to window structure; passing NULL is harmless.
  3838.  
  3839.    RESULT
  3840.     none
  3841.  
  3842.    SEE ALSO
  3843.     gtlayout.library/LT_LockWindow
  3844.  
  3845. gtlayout.library/LT_UpdateStrings           gtlayout.library/LT_UpdateStrings
  3846.  
  3847.    NAME
  3848.     LT_UpdateStrings -- Make sure all visible string buffer contents
  3849.                         get written into storage (v9).
  3850.  
  3851.    SYNOPSIS
  3852.     LT_UpdateStrings(LayoutHandle);
  3853.                             A0
  3854.  
  3855.     VOID LT_UpdateStrings(struct LayoutHandle *);
  3856.  
  3857.    FUNCTION
  3858.     The user can terminate input into a string gadget or an object
  3859.     derived from a string gadget by various means. They all have
  3860.     in common that the application receives no notification that
  3861.     the string gadget contents have changed. This is particularly
  3862.     nasty with objects which make use of LA_STRPTR or other
  3863.     tags. Using LT_UpdateStrings() you can force all visible string
  3864.     gadget objects to hand over their contents to the internal
  3865.     buffers. Do this before you eventually exit your input loop.
  3866.  
  3867.    INPUTS
  3868.     LayoutHandle - Pointer to LayoutHandle structure.
  3869.  
  3870.    RESULT
  3871.     none
  3872.  
  3873.